oxedyne/daimond — src/wasm/diamond.rs

140 KiB, 1 run

created by r2519314175:977, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	//! Diamond / crystal / fold substrate — the durable core of Daimond in the
2	//! browser.
3	//!
4	//! A Diamond is a durable container for a pursuit. Its reduced state is
5	//! the crystal, which is two files -- `crystal.json`, the memory, and
6	//! `crystal.html`, the page that renders it; a fold re-reduces a delta into
7	//! the memory; the log is per-Diamond and append-only. This module owns the
8	//! OPFS layout and the pure store operations; the `#[wasm_bindgen]`
9	//! surface that drives the crystal and reducer agents lives on
10	//! [`DaimondApp`](crate::wasm::app::DaimondApp) in [`crate::wasm::app`].
11	//!
12	//! OPFS layout, per Diamond id:
13	//!
14	//! ```text
15	//! diamonds/<id>/crystal.json the memory (agent writes, user may edit)
16	//! diamonds/<id>/crystal.html the page that renders it
17	//! diamonds/<id>/versions/NNNN.json a data KEYFRAME (0-padded): the memory in full
18	//! diamonds/<id>/versions/NNNN.jpatch a data DELTA: the splices from the version before it
19	//! diamonds/<id>/versions/NNNN.html a page KEYFRAME, ONLY where the page changed
20	//! diamonds/<id>/versions/NNNN.hpatch a page DELTA against the last version that changed it
21	//! diamonds/<id>/versions/NNNN.md pre-migration history: read-only, never written again
22	//! diamonds/<id>/.daimond/meta.json { name, crystal_version, updated, touched, tags }
23	//! diamonds/<id>/.daimond/log append-only, one JSON record per line
24	//! diamonds/<id>/.daimond/deltas/NNNN.md the raw delta a fold consumed, referenced by delta_ref
25	//! ```
26	//!
27	//! One version counter, shared by both files. A page snapshot exists only at the versions where
28	//! the page actually changed, so the page as at version N is the highest `M <= N` that has one --
29	//! see [`read_version_page`].
30	//!
31	//! Every version stores a keyframe or a patch, and nothing is ever pruned. A full copy at
32	//! every version cost 101,834 bytes per page edit of the shipped Log Life capp, against a
33	//! per-Diamond share of 4 MiB; a hundred edits of it now cost 628 KiB rather than 10.1 MB. When
34	//! a keyframe is due, what a patch may be recorded against, and which files rebuild version N are
35	//! [`crate::diamond_delta`]'s, which is portable and is tested against that page. This module is
36	//! the OPFS edge over it: it reads the directory, reads the chain, and refuses to let a version
37	//! stand until the file it just wrote has been read back and shown to rebuild it.
38	//!
39	//! Each log record is a single-line JSON object:
40	//! `{ id, ts, kind, agent, task, parent_crystal_version, crystal_version,
41	//! delta_ref, note }` with `kind` one of `create`, `edit`, `fold`.
42	//!
43	//! The store is app-local for now (a candidate for extraction into
44	//! `fe2o3_data` once its shape settles, per the v1 plan's D22); it is not
45	//! extracted here. Whole-file read-modify-write backs the append (the
46	//! synchronous single-writer OPFS path is deferred); single-user,
47	//! single-Diamond-at-a-time makes that sufficient for this stage.
48
49	use crate::diamond_link::{
50	Link,
51	Node,
52	fix_legacy_kinds,
53	normalise_note,
54	normalise_rel,
55	parse_links,
56	union_links,
57	update_link_in,
58	write_links,
59	};
60	use crate::diamond_delta::{self, Snap};
61	use crate::diamond_meta::{Meta, normalise_tags};
62	use crate::llm::{extract_json_string, json_escape};
63	use crate::protocol::generate_session_id;
64	use crate::tools::FileRoot;
65	use crate::wasm::{js_prop, js_str, opfs};
66
67	use oxedyne_fe2o3_core::prelude::*;
68	use oxedyne_fe2o3_core::wasm::{console_log, now_ms};
69	use oxedyne_fe2o3_ore::diff;
70
71	use wasm_bindgen::prelude::wasm_bindgen;
72	use wasm_bindgen::{JsCast, JsValue};
73
74
75	// ┌───────────────────────────────────────────────────────────────┐
76	// │ Path helpers │
77	// └───────────────────────────────────────────────────────────────┘
78
79	/// Daimond's own directory inside a Diamond: the metadata, the log, the deltas.
80	const STORE_DIR: &str = ".daimond";
81
82	/// What that directory was called before the Red -> Daimond rename, and still is in
83	/// every workspace made before it. See [`migrate`].
84	const LEGACY_STORE_DIR: &str = ".red";
85
86	/// The Diamond root directory.
87	const ROOT_DIR: &str = "diamonds";
88
89	/// What the root has been called before, oldest first.
90	///
91	/// The noun has moved twice: `foci` -> `facets` -> `diamonds`. A workspace is
92	/// migrated straight to the current root from whichever it holds, rather than
93	/// hop by hop, because a user who has not opened Daimond since before the first
94	/// rename would otherwise need two passes and there is no reason to make them
95	/// take one at a time. Order matters only for the message it lets us give.
96	const LEGACY_ROOT_DIRS: [&str; 2] = ["foci", "facets"];
97
98	/// What a Diamond's content file was called before the brief -> crystal rename.
99	const LEGACY_CRYSTAL_FILE: &str = "brief.md";
100
101	/// The Diamond directory, `diamonds/<id>`.
102	pub fn diamond_dir(id: &str) -> String {
103	fmt!("diamonds/{}", id)
104	}
105
106	/// The crystal's memory, `diamonds/<id>/crystal.json`.
107	fn crystal_data_path(id: &str) -> String {
108	fmt!("diamonds/{}/{}", id, crate::tools::CRYSTAL_DATA_FILE)
109	}
110
111	/// The crystal's page, `diamonds/<id>/crystal.html`.
112	fn crystal_page_path(id: &str) -> String {
113	fmt!("diamonds/{}/{}", id, crate::tools::CRYSTAL_PAGE_FILE)
114	}
115
116	/// The crystal as it was before the migration, `diamonds/<id>/crystal.md`.
117	///
118	/// Read only, and only as the last thing tried: it is what a Diamond holds until [`list`] has
119	/// converted it, and what one holds for ever if the conversion could not be written.
120	fn crystal_legacy_path(id: &str) -> String {
121	fmt!("diamonds/{}/{}", id, crate::tools::CRYSTAL_FILE_LEGACY)
122	}
123
124	/// The append-only log, `diamonds/<id>/.daimond/log`.
125	fn log_path(id: &str) -> String {
126	fmt!("diamonds/{}/{}/log", id, STORE_DIR)
127	}
128
129	/// The metadata file, `diamonds/<id>/.daimond/meta.json`.
130	fn meta_path(id: &str) -> String {
131	fmt!("diamonds/{}/{}/meta.json", id, STORE_DIR)
132	}
133
134	/// The directory a Diamond's snapshots live in, `diamonds/<id>/versions`.
135	fn versions_dir(id: &str) -> String {
136	fmt!("diamonds/{}/versions", id)
137	}
138
139	/// A data snapshot, `diamonds/<id>/versions/NNNN.json`. Written at every version.
140	fn version_data_path(id: &str, version: u64) -> String {
141	fmt!("{}/{:04}.json", versions_dir(id), version)
142	}
143
144	// What a snapshot of each file is called. A version holds the keyframe extension or the patch
145	// one and never both; where it somehow holds both, the keyframe wins, because that is the one
146	// that stands on its own -- see [`snapshot_chain`].
147	const DATA_KEYFRAME_EXT: &str = ".json";
148	const DATA_PATCH_EXT: &str = ".jpatch";
149	const PAGE_KEYFRAME_EXT: &str = ".html";
150	const PAGE_PATCH_EXT: &str = ".hpatch";
151
152	/// One version's snapshot of one file, whichever of the two it is.
153	fn snapshot_path(id: &str, version: u64, ext: &str) -> String {
154	fmt!("{}/{:04}{}", versions_dir(id), version, ext)
155	}
156
157	/// A snapshot from before the crystal became data, `diamonds/<id>/versions/NNNN.md`.
158	///
159	/// READ-ONLY, for ever. Nothing writes one again; the history view renders what is there as the
160	/// markdown it is, and a version from before the migration has one of these and neither of the
161	/// other two.
162	fn version_legacy_path(id: &str, version: u64) -> String {
163	fmt!("{}/{:04}.md", versions_dir(id), version)
164	}
165
166	/// A stored raw delta, `diamonds/<id>/.daimond/deltas/NNNN.md`, keyed by the
167	/// crystal version the fold produced.
168	fn delta_path(id: &str, version: u64) -> String {
169	fmt!("diamonds/{}/{}/deltas/{:04}.md", id, STORE_DIR, version)
170	}
171
172
173	// ┌───────────────────────────────────────────────────────────────┐
174	// │ Migration │
175	// └───────────────────────────────────────────────────────────────┘
176
177	/// Is there an EARLIER Diamond root whose entries have NOT been taken over?
178	///
179	/// After [`migrate_root`]'s merge, this is true only of a genuine id collision -- an id
180	/// present in both roots, which is the one case the merge leaves alone. It used to answer
181	/// the much larger question "is there an old root that will now never be found", which the
182	/// merge has made unaskable.
183	pub async fn legacy_root_waiting() -> Outcome<bool> {
184	for legacy in LEGACY_ROOT_DIRS.iter() {
185	let entries = match opfs::list_dir(FileRoot::Opfs, legacy).await {
186	Ok(e) => e,
187	Err(_) => continue, // no such root here
188	};
189	if entries.iter().any(\|(_, is_dir, _)\| *is_dir) {
190	return Ok(true);
191	}
192	}
193	Ok(false)
194	}
195
196	/// Bring the Diamond root forward from `foci/` or `facets/` to `diamonds/`, so a workspace
197	/// made before the Focus -> Diamond rename opens with every pursuit intact.
198	///
199	/// This runs before [`list`] reads the root, and before the per-Diamond [`migrate`], because
200	/// everything below depends on the new root existing. Without it a user's Foci would simply
201	/// not be found: `list_dir("diamonds")` would fail, the rail would come up empty, and every
202	/// crystal, version and fold record would read as though it had never existed.
203	///
204	/// Idempotent, and it never clobbers. A workspace already migrated has nothing to move. A
205	/// workspace holding BOTH roots has the entries that do not collide moved across, and the
206	/// ones that do left exactly where they are.
207	///
208	/// THE MERGE REPLACES A REFUSAL. Until 2026-08-07 a workspace that arrived holding both
209	/// roots was left alone entirely, which sounds cautious and is not: the old root is a
210	/// directory nothing reads, so those Diamonds were invisible for ever -- and the state was
211	/// reachable by an ordinary sequence of events, since creating a single Diamond makes
212	/// `diamonds/` exist and a backup, a sync from an older device or a folder adopted afterwards
213	/// can each bring an older root along later. Moving an entry whose id is not already in
214	/// `diamonds/` overwrites nothing, so it is strictly safer than leaving it unreachable. A
215	/// genuine id collision is the one case where merging really could lose work, and it is the
216	/// one case this does not attempt.
217	///
218	/// Returns whether anything moved.
219	async fn migrate_root() -> Outcome<bool> {
220	let mut moved = false;
221	// Newest legacy root first, so a workspace somehow holding both is taken from
222	// the one nearer to current and the older one merges around what it left.
223	for legacy in LEGACY_ROOT_DIRS.iter().rev() {
224	if !res!(opfs::exists(FileRoot::Opfs, legacy).await) {
225	continue;
226	}
227	if res!(migrate_one_root(legacy).await) {
228	moved = true;
229	}
230	}
231	Ok(moved)
232	}
233
234	/// Take `legacy` over into `diamonds/`, whole if it can and entry by entry if it cannot.
235	async fn migrate_one_root(legacy: &str) -> Outcome<bool> {
236	crate::wasm::entry::trail("migrate_one_root", legacy);
237	// Nothing to merge into: the whole directory in one move. Cheaper, and it
238	// carries anything a `list_dir` walk would not report.
239	if !res!(opfs::exists(FileRoot::Opfs, ROOT_DIR).await) {
240	res!(opfs::move_entry(FileRoot::Opfs, legacy, ROOT_DIR).await);
241	let ids = match opfs::list_dir(FileRoot::Opfs, ROOT_DIR).await {
242	Ok(e) => e.into_iter().filter(\|(_, d, _)\| *d).map(\|(n, _, _)\| n).collect(),
243	Err(_) => Vec::new(), // moved, but nothing to walk
244	};
245	res!(rewrite_delta_refs(legacy, &ids).await);
246	return Ok(true);
247	}
248
249	// Both roots. Move what does not collide; leave what does.
250	let entries = match opfs::list_dir(FileRoot::Opfs, legacy).await {
251	Ok(e) => e,
252	Err(_) => return Ok(false),
253	};
254	let mut ids: Vec<String> = Vec::new();
255	let mut collisions = 0usize;
256	for (name, is_dir, _size) in entries {
257	if !is_dir {
258	continue;
259	}
260	let to = fmt!("{}/{}", ROOT_DIR, name);
261	if res!(opfs::exists(FileRoot::Opfs, &to).await) {
262	// The same id in both roots. Which copy is the user's current work is
263	// not answerable from here, and overwriting the one they can see with
264	// one they cannot is the loss this whole function exists to avoid.
265	collisions += 1;
266	console_log(&fmt!(
267	"A Diamond '{}' is in both '{}' and '{}'; the older copy is left where it is.",
268	name, legacy, ROOT_DIR,
269	));
270	continue;
271	}
272	let from = fmt!("{}/{}", legacy, name);
273	res!(opfs::move_entry(FileRoot::Opfs, &from, &to).await);
274	ids.push(name);
275	}
276	if ids.is_empty() && collisions > 0 {
277	return Ok(false);
278	}
279	res!(rewrite_delta_refs(legacy, &ids).await);
280	// An emptied legacy root is deleted, so the next boot has nothing to walk and
281	// `legacy_root_waiting` stops reporting a root that holds nothing. One that
282	// still holds a collision stays, because it still holds the user's work.
283	if collisions == 0 {
284	if let Err(e) = opfs::delete_entry(FileRoot::Opfs, legacy, true).await {
285	console_log(&fmt!("The emptied '{}' root could not be removed: {}.", legacy, e));
286	}
287	}
288	Ok(!ids.is_empty())
289	}
290
291	/// Point every moved Diamond's log at its deltas under the new root.
292	///
293	/// A log record's `delta_ref` holds a path written when the fold was applied, so every
294	/// historical record still names `legacy/<id>/`; left alone, "view this delta" would fail on
295	/// every fold the user has.
296	async fn rewrite_delta_refs(legacy: &str, ids: &[String]) -> Outcome<()> {
297	for id in ids {
298	// The log is wherever this Diamond's store currently is, and a workspace
299	// old enough to predate the Red -> Daimond rename may still be on
300	// `.red/` -- [`migrate`] has not run yet, and cannot, because it
301	// addresses the new root this function is only now creating. So both are
302	// tried: looking only at `.daimond/` would skip exactly the oldest
303	// workspaces, leaving their `delta_ref` paths pointing at a root that no
304	// longer exists, which no later migration would match either.
305	for store in [STORE_DIR, LEGACY_STORE_DIR] {
306	let log = fmt!("{}/{}/{}/log", ROOT_DIR, id, store);
307	if !res!(opfs::exists(FileRoot::Opfs, &log).await) {
308	continue;
309	}
310	let bytes = res!(opfs::read_file(FileRoot::Opfs, &log).await);
311	let text = String::from_utf8_lossy(&bytes).to_string();
312	let fixed = text.replace(
313	&fmt!("{}/{}/", legacy, id),
314	&fmt!("{}/{}/", ROOT_DIR, id),
315	);
316	if fixed != text {
317	res!(opfs::write_file(FileRoot::Opfs, &log, fixed.as_bytes()).await);
318	}
319	}
320	}
321	Ok(())
322	}
323
324
325	/// Rename a Diamond's content file from `brief.md` to `crystal.md`.
326	///
327	/// The file holds the whole of what a Diamond knows, so this is the single most
328	/// destructive thing in the migration to get wrong: a Diamond whose crystal is not
329	/// found reads as an empty one, and an agent handed an empty crystal will happily
330	/// write a new one over the top of work it never saw.
331	///
332	/// Idempotent, and it never clobbers: a Diamond already migrated has no
333	/// `brief.md`, and one holding both files is left alone rather than merged.
334	async fn migrate_crystal_file(id: &str) -> Outcome<bool> {
335	let old = fmt!("{}/{}/{}", ROOT_DIR, id, LEGACY_CRYSTAL_FILE);
336	let new = crystal_legacy_path(id);
337	if !res!(opfs::exists(FileRoot::Opfs, &old).await) {
338	return Ok(false);
339	}
340	if res!(opfs::exists(FileRoot::Opfs, &new).await) {
341	return Ok(false);
342	}
343	res!(opfs::move_entry(FileRoot::Opfs, &old, &new).await);
344	Ok(true)
345	}
346
347
348	/// Convert a Diamond's crystal from markdown to data: `crystal.md` -> `crystal.json`.
349	///
350	/// Runs where [`migrate_crystal_file`] runs, on the same trigger, and carries the same two
351	/// properties for the same reason. Idempotent: a Diamond already converted has a
352	/// `crystal.json`, and the second check below is what sees it -- the markdown is kept, so the
353	/// absence of the OLD file is not what makes this safe to re-run. It never clobbers: a
354	/// Diamond holding both files is left exactly as it is rather than merged, because which of the
355	/// two is the user's current work is not answerable from here, and overwriting the one they can
356	/// see is the loss this whole function exists to avoid.
357	///
358	/// The conversion is [`crate::tools::crystal_from_markdown`], which enforces losslessness rather
359	/// than promising it: a shape it cannot render back byte for byte goes into one section verbatim.
360	/// It is still the most destructive thing in the migration to get wrong -- a Diamond whose crystal
361	/// is not found reads as an empty one, and an agent handed an empty crystal will write a new one
362	/// over the top of work it never saw.
363	///
364	/// THE MARKDOWN IS KEPT. An earlier draft of this deleted `crystal.md` once the data was
365	/// written and read back, to save a migrated Diamond carrying two live crystals in every sync
366	/// parcel. That trade is the wrong way round, and the asymmetry is the reason:
367	///
368	/// * The cost of keeping it is small and measured. A real workspace was thirteen Diamonds in
369	/// 15,786 bytes; doubling a crystal doubles a very small number.
370	/// * The cost of deleting it is unbounded. The self-check proves the BYTES round-trip and cannot
371	/// prove the STRUCTURE is right -- a `##` inside a fenced code block rejoins to the same bytes
372	/// whether or not the fence was honoured -- so a conversion can be wrong in a way nothing here
373	/// detects. Deleting on that would destroy the only correct copy, on every device, at the
374	/// moment of the release that introduced the bug.
375	/// * And it would not stay local. [`import_diamond`] deletes a Diamond's directory before
376	/// rewriting it, so a bad conversion propagates back over a good copy on the next sync. That is
377	/// the shape this project has already lost a user's tags to.
378	///
379	/// A later release removes the markdown, once the conversion has run against real workspaces
380	/// without complaint. Nothing reads it while `crystal.json` is there; it is ballast, and ballast
381	/// is cheap.
382	///
383	/// The data snapshot is written here too, at the version the Diamond already stands at, so
384	/// `versions/NNNN.json` exists from the migration instant rather than from the next edit. It is
385	/// written only where there is not one already, on the same never-clobber rule as everything else
386	/// in this function, and a Diamond whose metadata will not parse simply does not get one -- a
387	/// backfill is a convenience and must not be able to fail a migration.
388	///
389	/// # Arguments
390	/// * `id` - The Diamond whose crystal is to be converted.
391	async fn migrate_crystal_data(id: &str) -> Outcome<bool> {
392	let old = crystal_legacy_path(id);
393	let new = crystal_data_path(id);
394	if !res!(opfs::exists(FileRoot::Opfs, &old).await) {
395	return Ok(false); // converted already, or a Diamond newer than markdown
396	}
397	if res!(opfs::exists(FileRoot::Opfs, &new).await) {
398	return Ok(false); // both present: not ours to reconcile, and not ours to destroy
399	}
400	let bytes = res!(opfs::read_file(FileRoot::Opfs, &old).await);
401	let md = String::from_utf8_lossy(&bytes).to_string();
402	let json = crate::tools::crystal_from_markdown(&md).to_json();
403	res!(opfs::write_file(FileRoot::Opfs, &new, json.as_bytes()).await);
404
405	// The backfill. Best-effort throughout: the conversion has already succeeded by this point,
406	// and a Diamond that is converted but unsnapshotted is in a state `read_crystal_data` handles
407	// -- it falls through to the markdown history -- while a migration that reported failure
408	// would be re-run for ever over a file that is already there.
409	if let Ok(meta) = read_meta(id).await {
410	let at = version_data_path(id, meta.version);
411	match opfs::exists(FileRoot::Opfs, &at).await {
412	Ok(false) => {
413	if let Err(e) = opfs::write_file(FileRoot::Opfs, &at, json.as_bytes()).await {
414	console_log(&fmt!(
415	"Diamond '{}' was converted, but version {} could not be snapshotted as \
416	data: {}. Its markdown snapshot still stands.", id, meta.version, e));
417	}
418	}
419	_ => {}, // already there, or unreadable: either way, not ours to overwrite
420	}
421	}
422	Ok(true)
423	}
424
425
426	/// Move a Diamond's store from `.red/` to `.daimond/`, so a workspace made before the
427	/// rename opens with its history intact.
428	///
429	/// Without this a renamed Daimond simply would not find the old directory: [`read_meta`]
430	/// would fail, [`list`] would skip the Diamond, and a real pursuit -- its crystal versions, its
431	/// whole fold history -- would read as though it had never existed. The crystal itself
432	/// (`crystal.json` and `crystal.html`) and its snapshots sit outside the store directory and are
433	/// untouched either way; what moves here is the metadata, the log and the retained deltas.
434	///
435	/// The log's `delta_ref` field holds a path, written when the fold was applied, so the
436	/// records are rewritten as the directory moves -- otherwise every historical delta would
437	/// still point into `.red/` and "view this delta" would fail on exactly the folds the user
438	/// has had longest.
439	///
440	/// Idempotent, and it never clobbers: a Diamond already migrated has no `.red/` to move, and
441	/// one that somehow holds both directories is left entirely alone rather than merged.
442	/// Returns whether anything moved.
443	///
444	/// # Arguments
445	/// * `id` - The Diamond whose store is to be migrated.
446	async fn migrate(id: &str) -> Outcome<bool> {
447	let old = fmt!("diamonds/{}/{}", id, LEGACY_STORE_DIR);
448	let new = fmt!("diamonds/{}/{}", id, STORE_DIR);
449	if !res!(opfs::exists(FileRoot::Opfs, &old).await) {
450	return Ok(false); // nothing to move: a new Diamond, or one already migrated
451	}
452	if res!(opfs::exists(FileRoot::Opfs, &new).await) {
453	return Ok(false); // both present: not ours to reconcile, and not ours to destroy
454	}
455	res!(opfs::move_entry(FileRoot::Opfs, &old, &new).await);
456
457	// The log points at the deltas by path, and the deltas have just moved.
458	let log = log_path(id);
459	if res!(opfs::exists(FileRoot::Opfs, &log).await) {
460	let bytes = res!(opfs::read_file(FileRoot::Opfs, &log).await);
461	let text = String::from_utf8_lossy(&bytes).to_string();
462	let fixed = text.replace(
463	&fmt!("diamonds/{}/{}/deltas/", id, LEGACY_STORE_DIR),
464	&fmt!("diamonds/{}/{}/deltas/", id, STORE_DIR),
465	);
466	if fixed != text {
467	res!(opfs::write_file(FileRoot::Opfs, &log, fixed.as_bytes()).await);
468	}
469	}
470	Ok(true)
471	}
472
473
474	/// Read the crystal's memory as it stood at `version`.
475	///
476	/// Every fold and every hand-edit snapshots the crystal, but nothing has ever
477	/// read one back, so an accepted fold that mangled the crystal could not be
478	/// undone. This is what makes the history recoverable rather than merely
479	/// recorded.
480	///
481	/// A version from before the migration has a `.md` and no `.json`, and it is returned as the
482	/// markdown it is: the caller renders what it is given rather than being told which it got, which
483	/// is what "the history view renders that as it always did" costs.
484	pub async fn read_version(id: &str, version: u64) -> Outcome<String> {
485	let snaps = snapshot_chain(id, DATA_KEYFRAME_EXT, DATA_PATCH_EXT).await;
486	if snaps.iter().any(\|(n, _)\| *n == version) {
487	// A version that HAS a snapshot and cannot be rebuilt from it is a fault to report.
488	// Reaching for the pre-migration file of the same number here would answer a question
489	// about a version that no longer exists with one from a Diamond that no longer does.
490	let chain = res!(diamond_delta::plan_at(&snaps, version));
491	let bytes = res!(follow(id, &chain, DATA_KEYFRAME_EXT, DATA_PATCH_EXT).await);
492	return Ok(String::from_utf8_lossy(&bytes).to_string());
493	}
494	let bytes = res!(opfs::read_file(FileRoot::Opfs, &version_legacy_path(id, version)).await);
495	Ok(String::from_utf8_lossy(&bytes).to_string())
496	}
497
498	/// Read the PAGE as it stood at `version`, by walking back to the last one that changed it.
499	///
500	/// This walk is the whole cost of not copying the page into every snapshot. A
501	/// `versions/NNNN.html` is written only where the page actually moved, so most versions have
502	/// none, and asking for the page at one of those is not asking for nothing -- it is asking for
503	/// whatever page was on screen at the time, which is the last one written at or before it. Read
504	/// naively, every version between two page edits would report a Diamond with no page at all, and
505	/// the history view would show the built-in fallback for stretches where the user was looking at
506	/// their own page the whole time.
507	///
508	/// An empty string means no page was ever stored at or before that version, which is what every
509	/// pre-migration version says. Nothing here invents a default: the shipped page is a JS const,
510	/// and this stores bytes.
511	///
512	/// # Arguments
513	/// * `id` - The Diamond.
514	/// * `version` - The version to read the page as at.
515	pub async fn read_version_page(id: &str, version: u64) -> Outcome<String> {
516	// One directory walk rather than a read per version stepping backwards. A Diamond at version
517	// 300 whose page never changed would otherwise cost 300 failed OPFS reads to answer "none",
518	// on the device least able to afford them.
519	let snaps = snapshot_chain(id, PAGE_KEYFRAME_EXT, PAGE_PATCH_EXT).await;
520	Ok(res!(page_at(id, version, &snaps).await).unwrap_or_default())
521	}
522
523	/// The page as at the newest version at or before `version`, or `None` where none was ever
524	/// stored at or before it.
525	///
526	/// The difference from [`read_version_page`] is the difference between "the page was empty" and
527	/// "there was no page", which the caller that is about to RECORD a version has to be able to
528	/// tell: a version recorded against a parent that does not exist is exactly the fault the whole
529	/// chain is built to refuse.
530	async fn page_at(id: &str, version: u64, snaps: &[(u64, Snap)])
531	-> Outcome<Option<String>>
532	{
533	let chain = match res!(diamond_delta::plan_upto(snaps, version)) {
534	Some((_, c)) => c,
535	None => return Ok(None),
536	};
537	let bytes = res!(follow(id, &chain, PAGE_KEYFRAME_EXT, PAGE_PATCH_EXT).await);
538	Ok(Some(String::from_utf8_lossy(&bytes).to_string()))
539	}
540
541	/// Every snapshot a Diamond holds for one file, with what each one is.
542	///
543	/// One directory walk answers both extensions, because a reader needs them together: whether a
544	/// version is a full copy or splices over the one before it decides what has to be read next.
545	/// A version that holds both -- which is what a patch abandoned by a failed verification would
546	/// leave, if the delete after it did not land -- is taken as the full copy.
547	///
548	/// # Arguments
549	/// * `id` - The Diamond.
550	/// * `kf_ext` - The extension a full copy carries, including its dot.
551	/// * `patch_ext` - The extension splices carry, including its dot.
552	async fn snapshot_chain(id: &str, kf_ext: &str, patch_ext: &str) -> Vec<(u64, Snap)> {
553	classify(&version_entries(id).await, kf_ext, patch_ext)
554	}
555
556	/// The `versions/` listing, once, for a caller that is going to classify it twice.
557	///
558	/// A missing directory is no snapshots and not a failure: a Diamond older than they are, or
559	/// one that has been emptied.
560	async fn version_entries(id: &str) -> Vec<(String, bool, u64)> {
561	match opfs::list_dir(FileRoot::Opfs, &versions_dir(id)).await {
562	Ok(e) => e,
563	Err(_) => Vec::new(),
564	}
565	}
566
567	/// One listing read as one file's snapshots. See [`snapshot_chain`] for the rules.
568	fn classify(entries: &[(String, bool, u64)], kf_ext: &str, patch_ext: &str) -> Vec<(u64, Snap)> {
569	let mut out: Vec<(u64, Snap)> = Vec::new();
570	for (name, is_dir, _size) in entries {
571	if *is_dir {
572	continue;
573	}
574	let found = match name.strip_suffix(kf_ext).and_then(\|s\| s.parse::<u64>().ok()) {
575	Some(n) => Some((n, Snap::Keyframe)),
576	None => name.strip_suffix(patch_ext)
577	.and_then(\|s\| s.parse::<u64>().ok())
578	.map(\|n\| (n, Snap::Patch)),
579	};
580	let (n, kind) = match found {
581	Some(f) => f,
582	None => continue, // somebody else's file, passed over rather than guessed at
583	};
584	match out.iter_mut().find(\|(m, _)\| *m == n) {
585	Some(seen) => if kind == Snap::Keyframe {
586	seen.1 = Snap::Keyframe;
587	},
588	None => out.push((n, kind)),
589	}
590	}
591	out
592	}
593
594	/// Read one version's chain off the disk and rebuild the file from it.
595	///
596	/// `chain` is what [`crate::diamond_delta::plan_at`] or
597	/// [`crate::diamond_delta::plan_upto`] gave: the keyframe first, then every patch over it in
598	/// order. A missing file is an error and not a shorter chain -- a rebuild that stopped early
599	/// would return an older version wearing this one's number.
600	async fn follow(id: &str, chain: &[u64], kf_ext: &str, patch_ext: &str)
601	-> Outcome<Vec<u8>>
602	{
603	let head = match chain.first() {
604	Some(n) => *n,
605	None => return Err(err!(
606	"Diamond '{}' asked for a version with no chain to rebuild it from.", id;
607	Bug, Missing)),
608	};
609	let kf = res!(opfs::read_file(FileRoot::Opfs, &snapshot_path(id, head, kf_ext)).await);
610	let mut patches: Vec<Vec<u8>> = Vec::with_capacity(chain.len().saturating_sub(1));
611	for n in &chain[1..] {
612	patches.push(res!(
613	opfs::read_file(FileRoot::Opfs, &snapshot_path(id, *n, patch_ext)).await));
614	}
615	diamond_delta::materialise(kf, &patches)
616	}
617
618	/// Every version a Diamond holds a snapshot for with the given extension, unordered.
619	///
620	/// For the pre-migration `.md` snapshots, which have no chain: nothing writes one again, so a
621	/// version either has one or does not. [`snapshot_chain`] is what the two live files use.
622	///
623	/// A name that does not parse is somebody else's file and is passed over rather than guessed at.
624	/// A missing `versions/` directory is no snapshots, not a failure: a Diamond older than they are,
625	/// or one that has been emptied.
626	///
627	/// # Arguments
628	/// * `id` - The Diamond.
629	/// * `ext` - The extension including its dot.
630	async fn snapshot_versions(id: &str, ext: &str) -> Vec<u64> {
631	let entries = match opfs::list_dir(FileRoot::Opfs, &versions_dir(id)).await {
632	Ok(e) => e,
633	Err(_) => return Vec::new(),
634	};
635	let mut out: Vec<u64> = Vec::new();
636	for (name, is_dir, _size) in entries {
637	if is_dir {
638	continue;
639	}
640	if let Some(n) = name.strip_suffix(ext).and_then(\|s\| s.parse::<u64>().ok()) {
641	out.push(n);
642	}
643	}
644	out
645	}
646
647
648	// ┌───────────────────────────────────────────────────────────────┐
649	// │ Metadata │
650	// └───────────────────────────────────────────────────────────────┘
651
652	/// Read a Diamond's metadata.
653	/// The most a `meta.json` may be worth reading.
654	///
655	/// It holds a name, a version, two stamps, at most eight tags of at most
656	/// twenty-four characters, and a short list of toolkit names. A kilobyte is a
657	/// generous one; sixty-four is beyond argument. Anything past this is damage.
658	const META_MAX: u32 = 65_536;
659
660	/// A Diamond's name, read back off its own crystal.
661	///
662	/// The last resort for a Diamond whose `meta.json` lost its name. A crystal carries a `title` by
663	/// construction — the default Diamonds are written that way, the migration lifts it out of the
664	/// opening `# ` heading, and every fold is asked to keep it — so it is the one place the name
665	/// survives outside the metadata. [`read_crystal_data`] already falls back through the version
666	/// snapshots and through a legacy markdown crystal, so this reaches even a Diamond whose crystal
667	/// file has gone.
668	///
669	/// The `# ` scan stays as the second try, for a Diamond holding markdown that no conversion has
670	/// reached — this runs inside [`list`], which is also where the conversion runs, and the order of
671	/// two repairs over one file is not a thing to depend on.
672	///
673	/// Returns `None` rather than a guess when there is neither to read: an
674	/// invented name would be worse than an empty one, because the user could not
675	/// tell it from the name they chose.
676	async fn name_from_crystal(id: &str) -> Option<String> {
677	let text = read_crystal_data(id).await.ok()?;
678	if let Some(title) = extract_json_string(&text, "title") {
679	let name: String = title.trim().chars().take(80).collect();
680	if !name.is_empty() {
681	return Some(name);
682	}
683	}
684	for line in text.lines().take(20) {
685	let t = line.trim();
686	if let Some(rest) = t.strip_prefix("# ") {
687	let name: String = rest.trim().chars().take(80).collect();
688	if !name.is_empty() {
689	return Some(name);
690	}
691	}
692	}
693	None
694	}
695
696	/// Read a Diamond's metadata, WITHOUT trusting the file's size.
697	///
698	/// THIS IS THE iPHONE LOOP. Two of one user's fifteen Diamonds had a `meta.json`
699	/// of roughly 117 MB and 702 MB, and this function read them whole — twice over,
700	/// because `from_utf8_lossy().to_string()` copies again. The device's own trail
701	/// caught it in the act:
702	///
703	/// list entry 19fb11892cdc heap 1M
704	/// HEAP GREW read_meta +234M -> 235M
705	/// …
706	/// HEAP GREW read_meta +1404M -> 1639M
707	/// boot <- the tab is gone
708	///
709	/// Wasm linear memory never shrinks, so 1.6 GB stood for the life of the tab and
710	/// iOS took it away — on every boot, which is the whole of the login loop that
711	/// ran for five sessions and produced seven wrong diagnoses.
712	///
713	/// So the size is asked BEFORE the bytes are, and only the front of an oversized
714	/// file is read. That is a graceful degradation rather than a refusal: `to_json`
715	/// writes `name`, `crystal_version`, `updated` and `touched` FIRST, so a 64 KB
716	/// prefix still recovers everything that orders the rail and drives the merge.
717	/// What is lost is tags — which is the right thing to lose, because the tags
718	/// array is the only unbounded field in the file and therefore the prime
719	/// suspect for what made it enormous.
720	///
721	/// A Diamond whose metadata is damaged must still LIST and still OPEN. Dropping
722	/// it would be answering a bug the user can report with one they can only mourn.
723	async fn read_meta(id: &str) -> Outcome<Meta> {
724	let (bytes, total) = res!(opfs::read_file_capped(FileRoot::Opfs, &meta_path(id), META_MAX).await);
725	if total > META_MAX as f64 {
726	// Loud, and in the durable trail: this is data damage, the user cannot
727	// see it, and the next write is about to heal it silently.
728	crate::wasm::entry::trail("META HUGE",
729	&fmt!("{} is {}KB — read the first {}KB only", id,
730	(total / 1024.0) as u64, META_MAX / 1024));
731	console_log(&fmt!(
732	"Diamond '{}' has a metadata file of {} bytes, which cannot be right. Only the first \
733	{} were read; its tags are dropped and will be rewritten on the next change.",
734	id, total as u64, META_MAX));
735	}
736	let s = String::from_utf8_lossy(&bytes);
737	if total > META_MAX as f64 {
738	// THE SHAPE OF THE DAMAGE, BEFORE THE REPAIR ERASES IT.
739	//
740	// The repair below is about to rewrite this file, and once it has, the
741	// only record of what went wrong is gone. What is still not known is how
742	// a metadata file reached 702 MB: forty million short tags, or one
743	// enormous one, or a `name` that grew, are three different bugs with
744	// three different fixes.
745	//
746	// COUNTS AND LENGTHS ONLY, never the text of a tag. A tag is something
747	// the user typed, and `breadcrumb.js` promises the trail holds nothing
748	// that could not be read aloud in a bug report. The shape answers the
749	// question and the content is not needed for it.
750	let prefix = &s[..s.len().min(META_MAX as usize)];
751	let quotes = prefix.matches('"').count();
752	let commas = prefix.matches(',').count();
753	let tags_at = prefix.find("\"tags\":").map(\|i\| i as i64).unwrap_or(-1);
754	let name_len = extract_json_string(prefix, "name").map(\|n\| n.len()).unwrap_or(0);
755	crate::wasm::entry::trail("META SHAPE",
756	&fmt!("{} name={}B tags@{} quotes={} commas={} in first {}KB",
757	id, name_len, tags_at, quotes, commas, META_MAX / 1024));
758	}
759	let meta = Meta::from_json(&s);
760	if total > META_MAX as f64 {
761	// AND PUT IT RIGHT, HERE, rather than waiting for something else to
762	// write. A read that merely tolerates the damage leaves 702 MB on disk
763	// for ever, and the file's SIZE has consequences of its own: the sync
764	// budget is estimated from bytes on disk (`export_size`), so an
765	// unrepaired Diamond is one the account can never send again. The user
766	// saw exactly that — the loop stopped and a notice said fifteen Diamonds
767	// would not fit.
768	//
769	// Safe because `to_json` writes the name, the version and both stamps
770	// FIRST, so the 64 KB prefix carried all of them; what is dropped is the
771	// tags array, which is the damage. Best-effort: a repair that cannot be
772	// written must not stop the Diamond being listed.
773	// AND NEVER OVER A NAME IT COULD NOT READ. If the prefix did not yield a
774	// name, the parse did not find what it expected and the file is not the
775	// shape assumed here. Keeping 702 MB on disk is a bad outcome; replacing
776	// a Diamond's name with nothing is a worse one, and it is not reversible.
777	// The oversized file stays, `read_meta` keeps coping with it, and the
778	// trail says the repair declined.
779	if meta.name.trim().is_empty() {
780	crate::wasm::entry::trail("META NOT HEALED", &fmt!("{} — no name parsed, file left alone", id));
781	} else {
782	match write_meta(id, &meta).await {
783	Ok(()) => crate::wasm::entry::trail("META HEALED", id),
784	Err(e) => console_log(&fmt!("Diamond '{}' could not have its metadata repaired: {}", id, e)),
785	}
786	}
787	}
788	Ok(meta)
789	}
790
791	/// Write a Diamond's metadata.
792	async fn write_meta(id: &str, meta: &Meta) -> Outcome<()> {
793	opfs::write_file(FileRoot::Opfs, &meta_path(id), meta.to_json().as_bytes()).await
794	}
795
796	/// Stamp a Diamond as changed, without saying it was worked on.
797	///
798	/// Every mutation of anything inside `diamonds/<id>/` moves `touched`, because
799	/// `touched` is what decides whose copy the other device takes. A change that
800	/// moved nothing would simply not travel: the merge would find the two copies
801	/// equally fresh and keep its own, which is how tagging used to be invisible
802	/// across devices -- and worse, how a later stamped edit on the other device
803	/// came to look strictly fresher and replace the tagged copy wholesale.
804	///
805	/// `updated` is left alone here, deliberately. It means worked on and orders
806	/// the rail; the callers that mean that (see [`rename`], [`snapshot`]) move it
807	/// themselves.
808	pub async fn touch(id: &str) -> Outcome<()> {
809	let mut meta = res!(read_meta(id).await);
810	meta.touched = now_ms() as u64;
811	write_meta(id, &meta).await
812	}
813
814
815	// ┌───────────────────────────────────────────────────────────────┐
816	// │ Log records │
817	// └───────────────────────────────────────────────────────────────┘
818
819	/// One append-only log record. `parent` uses `-1` for "no parent"
820	/// (the `create` record), matching the JSON the surface returns.
821	struct LogRecord {
822	id: String,
823	ts: u64,
824	kind: &'static str,
825	agent: String,
826	task: String,
827	parent: i64,
828	version: u64,
829	delta_ref: String,
830	note: String,
831	}
832
833	impl LogRecord {
834
835	/// Serialise to a compact single-line JSON object.
836	fn to_json(&self) -> String {
837	fmt!(
838	"{{\"id\":\"{}\",\"ts\":{},\"kind\":\"{}\",\"agent\":\"{}\",\
839	\"task\":\"{}\",\"parent_crystal_version\":{},\
840	\"crystal_version\":{},\"delta_ref\":\"{}\",\"note\":\"{}\"}}",
841	json_escape(&self.id), self.ts, self.kind, json_escape(&self.agent),
842	json_escape(&self.task), self.parent, self.version,
843	json_escape(&self.delta_ref), json_escape(&self.note),
844	)
845	}
846	}
847
848	/// Append a record to a Diamond's log.
849	///
850	/// OPFS exposes whole-file writes only, so the append is read-modify-write
851	/// (single-user, single-Diamond makes that safe for this stage; the
852	/// synchronous single-writer WAL is deferred).
853	async fn append_log(id: &str, rec: &LogRecord) -> Outcome<()> {
854	let path = log_path(id);
855	let mut buf = match opfs::exists(FileRoot::Opfs, &path).await {
856	Ok(true) => {
857	let bytes = res!(opfs::read_file(FileRoot::Opfs, &path).await);
858	String::from_utf8_lossy(&bytes).to_string()
859	}
860	_ => String::new(),
861	};
862	buf.push_str(&rec.to_json());
863	buf.push('\n');
864	opfs::write_file(FileRoot::Opfs, &path, buf.as_bytes()).await
865	}
866
867
868	// ┌───────────────────────────────────────────────────────────────┐
869	// │ Diamond operations │
870	// └───────────────────────────────────────────────────────────────┘
871
872	/// Create a Diamond: its directory, an empty `crystal.json`, version `0000`, a
873	/// `meta.json`, and a `create` log record. Returns the new Diamond id.
874	///
875	/// No page. A new Diamond renders on the shipped default until something writes one, and the
876	/// default is a JS const that this side never sees; writing an empty `crystal.html` here would
877	/// only put a file on disk that means the same as no file.
878	pub async fn create(name: &str) -> Outcome<String> {
879	create_at(name, &generate_session_id()).await
880	}
881
882	/// Create a Diamond AT A KNOWN ID, or answer with the id if one is already there.
883	///
884	/// This exists because a random id and a per-device flag cannot agree across a sync. The two
885	/// default Diamonds are seeded by every device separately -- the "already seeded" fact lives in
886	/// `localStorage`, which does not travel -- and each minted its own random id, so two devices
887	/// produced two Optimisers and two Helps, and the merge kept all four. The name check in
888	/// `seedDefaultDiamonds` never saw it, because it reads the local list and the other device's
889	/// copy has not arrived yet.
890	///
891	/// Seeding at a fixed id makes the two devices create the SAME object, so the merge has one thing
892	/// to keep rather than two things to add. No flag, no coordination, no ordering.
893	///
894	/// It is idempotent by construction: a second call finds the meta already written and returns
895	/// without touching the crystal, so a device that seeds twice cannot flatten what the first pass
896	/// or the user has since put there.
897	///
898	/// # Arguments
899	/// * `name` - The Diamond's name.
900	/// * `id` - The id to create it at. Hex, in the shape [`generate_session_id`] produces.
901	pub async fn create_at(name: &str, id: &str) -> Outcome<String> {
902	// ALREADY THERE IS A SUCCESS, and it must not rewrite anything: this is the path a second
903	// device takes, and by then the Diamond may hold a crystal somebody has worked on.
904	if read_meta(id).await.is_ok() {
905	return Ok(id.to_string());
906	}
907	create_fresh(name, id).await
908	}
909
910	async fn create_fresh(name: &str, id: &str) -> Outcome<String> {
911	let id = id.to_string();
912	let now = now_ms() as u64;
913
914	// Empty crystal plus its version-0 snapshot.
915	res!(opfs::write_file(FileRoot::Opfs, &crystal_data_path(&id), b"").await);
916	res!(opfs::write_file(FileRoot::Opfs, &version_data_path(&id, 0), b"").await);
917
918	let meta = Meta {
919	name: name.to_string(),
920	version: 0,
921	updated: now,
922	touched: now,
923	tags: Vec::new(),
924	// Off by default, which is the whole shape of a grant: nobody has said yes yet.
925	kits: Vec::new(),
926	};
927	res!(write_meta(&id, &meta).await);
928
929	let rec = LogRecord {
930	id: generate_session_id(),
931	ts: now,
932	kind: "create",
933	agent: "user".to_string(),
934	task: "create diamond".to_string(),
935	parent: -1,
936	version: 0,
937	delta_ref: String::new(),
938	note: name.to_string(),
939	};
940	res!(append_log(&id, &rec).await);
941	Ok(id)
942	}
943
944	/// Rename a Diamond, updating `meta.json`'s name and both its stamps.
945	pub async fn rename(id: &str, name: &str) -> Outcome<()> {
946	let now = now_ms() as u64;
947	let mut meta = res!(read_meta(id).await);
948	meta.name = name.to_string();
949	meta.updated = now;
950	meta.touched = now;
951	res!(write_meta(id, &meta).await);
952	Ok(())
953	}
954
955	/// Set a Diamond's tags, replacing whatever it held, and stamp it updated.
956	///
957	/// The tags are normalised here rather than taken on trust, so the store stays
958	/// clean whatever the caller sends (see
959	/// [`normalise_tags`](crate::diamond_meta::normalise_tags)).
960	///
961	/// Nothing is appended to the log, because the log is the crystal's audit trail
962	/// and a tag is not crystal state. Tagging leaves the version alone.
963	///
964	/// It leaves `updated` alone too, which is deliberate. The rail is ordered by
965	/// `updated`, meaning most recently worked on; filing is not working on it, so
966	/// tagging must not reorder the rail. Otherwise tidying a few Diamonds in one
967	/// sitting would shuffle them all to the top and lose the order that was the
968	/// point of the sort. This is why it differs from `rename`, which does stamp.
969	///
970	/// It does move `touched`, because the tags are content and content has to
971	/// travel. While there was one stamp this could not be had both ways: leaving
972	/// it alone meant the tags never reached the other device AND that the other
973	/// device's untagged copy became strictly fresher the moment anything there was
974	/// renamed or edited, at which point the merge replaced the tagged copy with it
975	/// and the tags were gone. A user lost real tags that way.
976	pub async fn set_tags(id: &str, tags: &[String]) -> Outcome<()> {
977	let mut meta = res!(read_meta(id).await);
978	meta.tags = normalise_tags(tags);
979	meta.touched = now_ms() as u64;
980	res!(write_meta(id, &meta).await);
981	Ok(())
982	}
983
984	/// Set which toolchains this Diamond is granted, replacing whatever it held.
985	///
986	/// Stamped and normalised exactly as [`set_tags`] is, and for the same two reasons: filing a
987	/// permission is not working on the Diamond, so the rail must not reorder; and the grant is content
988	/// that has to reach the user's other devices, so `touched` moves.
989	///
990	/// The names are normalised here rather than taken on trust (see
991	/// [`normalise_kits`](crate::diamond_meta::normalise_kits)) -- and unlike a tag, a name this build
992	/// does not know is dropped, because what is stored here decides what a command may reach outside
993	/// the workspace and a grant nobody can act on is not a grant.
994	///
995	/// # Arguments
996	/// * `id` - The Diamond.
997	/// * `kits` - The toolkit names the user granted, as `Toolkit::name` spells them.
998	pub async fn set_toolkits(id: &str, kits: &[String]) -> Outcome<()> {
999	let mut meta = res!(read_meta(id).await);
1000	meta.kits = crate::diamond_meta::normalise_kits(kits);
1001	meta.touched = now_ms() as u64;
1002	res!(write_meta(id, &meta).await);
1003	Ok(())
1004	}
1005
1006	/// Delete a Diamond: remove its whole directory (crystal, versions, log, meta).
1007	pub async fn delete(id: &str) -> Outcome<()> {
1008	opfs::delete_entry(FileRoot::Opfs, &diamond_dir(id), true).await
1009	}
1010
1011	/// List every Diamond, returning a JSON array of
1012	/// `{ id, name, crystal_version, updated, touched, tags }` ordered by
1013	/// most-recently updated first.
1014	///
1015	/// Both stamps travel in the row because they answer different questions: the
1016	/// order below is `updated` (worked on), while the cross-device merge compares
1017	/// `touched` (changed at all).
1018	///
1019	/// This is the one door every Diamond passes through before it can be opened, so it is where
1020	/// a workspace made before the rename is migrated (see [`migrate`]). A Diamond that fails to
1021	/// migrate is left in the list rather than dropped from it: the metadata read below decides
1022	/// that, and a Diamond the user can see and cannot open is a bug they can report, while one
1023	/// that has silently vanished is a bug they can only mourn.
1024	pub async fn list() -> Outcome<String> {
1025	// INSTRUMENTED, because this is the call that hangs on one iPhone and a hang
1026	// has nothing to report: no error, no panic, just a `Promise` that never
1027	// settles. Four diagnoses were made from reading this file and all four were
1028	// wrong. The lines below are what the device says about itself.
1029	crate::wasm::entry::trail("list_diamonds", "start");
1030
1031	// Before the root is read, because before the rename the root itself was elsewhere.
1032	crate::wasm::entry::trail("list", "migrate_root");
1033	if let Err(e) = migrate_root().await {
1034	console_log(&fmt!("The diamonds/ root could not be migrated from an earlier one: {}", e));
1035	}
1036	// A missing `diamonds/` root simply means no Diamonds yet.
1037	let entries = match opfs::list_dir(FileRoot::Opfs, ROOT_DIR).await {
1038	Ok(e) => e,
1039	Err(_) => { crate::wasm::entry::trail("list", "no diamonds/ root"); return Ok("[]".to_string()); },
1040	};
1041	crate::wasm::entry::trail("list", &fmt!("{} entries", entries.len()));
1042	let mut rows: Vec<(String, Meta)> = Vec::new();
1043	for (name, is_dir, _size) in entries {
1044	if !is_dir {
1045	continue;
1046	}
1047	// THE HEAP, PER CALL, AND THIS IS WHY.
1048	//
1049	// The phone's trail settled that wasm linear memory reaches 1639 MB
1050	// inside this loop and that the tab is killed a second later. It reaches
1051	// 235 MB across the first three entries and 1639 MB across the next four,
1052	// and it does so with the sync engine switched off — so the walk itself is
1053	// the whole of it. What the trail could NOT say is which of the three
1054	// calls below allocates, because they were one line together.
1055	//
1056	// Growth only, and only when it crosses a megabyte, so an ordinary walk
1057	// writes one row per entry rather than four. Six diagnoses of this bug
1058	// were made by reading source and all six were wrong; this is the line
1059	// that makes a seventh unnecessary.
1060	let mut was = crate::wasm::entry::heap_mb();
1061	crate::wasm::entry::trail("list entry", &fmt!("{} heap {}M", name, was));
1062	let grew = \|phase: &str, was: &mut u32\| {
1063	let now = crate::wasm::entry::heap_mb();
1064	if now > *was {
1065	crate::wasm::entry::trail("HEAP GREW", &fmt!("{} +{}M -> {}M", phase, now - *was, now));
1066	*was = now;
1067	}
1068	};
1069	// Before the metadata is read, because before the rename it was somewhere else.
1070	if let Err(e) = migrate(&name).await {
1071	console_log(&fmt!("Diamond '{}' could not be migrated to .daimond/: {}", name, e));
1072	}
1073	grew("migrate", &mut was);
1074	// And before the crystal is read, because it was called brief.md.
1075	if let Err(e) = migrate_crystal_file(&name).await {
1076	console_log(&fmt!("Diamond '{}' could not have its crystal renamed: {}", name, e));
1077	}
1078	grew("migrate_crystal", &mut was);
1079	// And then, on the same trigger and for the same reason, because it was markdown.
1080	if let Err(e) = migrate_crystal_data(&name).await {
1081	console_log(&fmt!("Diamond '{}' could not have its crystal converted: {}", name, e));
1082	}
1083	grew("migrate_crystal_data", &mut was);
1084	let mut meta = match read_meta(&name).await {
1085	Ok(m) => m,
1086	Err(_) => continue, // not a Diamond dir / no metadata
1087	};
1088	grew("read_meta", &mut was);
1089	// A NAMELESS DIAMOND GETS ITS NAME BACK OFF ITS OWN CRYSTAL.
1090	//
1091	// This exists because a repair of mine destroyed fifteen of them. An
1092	// earlier build rebuilt every imported `meta.json` and wrote whatever it
1093	// parsed, so one sync left a user with fifteen tiles carrying nothing but
1094	// a cog. The guards in `import_diamond` and `read_meta` stop it happening
1095	// again; this is what puts right the accounts it already happened to.
1096	//
1097	// The crystal opens `# <name>` — `seedDefaultDiamonds` writes it that way
1098	// and so does every fold — so the heading is the name, recoverable from
1099	// the one file a Diamond certainly has. Written back, so it costs one
1100	// read per damaged Diamond once and nothing ever again.
1101	if meta.name.trim().is_empty() {
1102	if let Some(from_crystal) = name_from_crystal(&name).await {
1103	crate::wasm::entry::trail("NAME RECOVERED", &name);
1104	meta.name = from_crystal;
1105	if let Err(e) = write_meta(&name, &meta).await {
1106	console_log(&fmt!("Diamond '{}' could not keep its recovered name: {}", name, e));
1107	}
1108	}
1109	}
1110	rows.push((name, meta));
1111	}
1112	// Most-recently updated first.
1113	rows.sort_by(\|a, b\| b.1.updated.cmp(&a.1.updated));
1114	let items: Vec<String> = rows.iter().map(\|(id, m)\| {
1115	fmt!(
1116	"{{\"id\":\"{}\",\"name\":\"{}\",\"crystal_version\":{},\"updated\":{},\
1117	\"touched\":{},\"tags\":{},\"toolkits\":{}}}",
1118	json_escape(id), json_escape(&m.name), m.version, m.updated,
1119	m.touched, m.tags_json(), m.kits_json(),
1120	)
1121	}).collect();
1122	Ok(fmt!("[{}]", items.join(",")))
1123	}
1124
1125	/// Read a Diamond's current crystal data, as the JSON text it is stored as.
1126	///
1127	/// A Diamond that LISTS must OPEN. [`list`] admits one on its metadata alone -- deliberately, so
1128	/// that a broken Diamond is a bug the user can report rather than one they can only mourn -- and
1129	/// this used to be a bare read, so a Diamond whose crystal was missing threw `NotFoundError`
1130	/// at the panel and could not be opened at all. Four live paths arrive at that state, an
1131	/// interrupted import among them.
1132	///
1133	/// So the version snapshots are used for what they have always been: the store's own redundancy.
1134	/// Four things are tried, in this order, and the order is the whole point:
1135	///
1136	/// 1. `crystal.json`, which is where it should be.
1137	/// 2. The newest `versions/NNNN.json`, the store's own copy of the same bytes.
1138	/// 3. A legacy markdown crystal -- `crystal.md`, then the newest `versions/NNNN.md` -- converted
1139	/// on the way out. This reaches a Diamond that has never been through [`list`], one whose
1140	/// conversion could not be written, and -- because [`migrate_crystal_data`] deliberately keeps
1141	/// the markdown rather than deleting it -- any migrated Diamond that later loses its data file.
1142	/// 4. Empty, with a console line saying so.
1143	///
1144	/// The last of those is the most destructive failure in this whole change, which is why there
1145	/// are three things before it: a Diamond whose crystal is not found reads as an empty one, and an
1146	/// agent handed an empty crystal will happily write a new one over the top of work it never saw.
1147	pub async fn read_crystal_data(id: &str) -> Outcome<String> {
1148	if let Ok(bytes) = opfs::read_file(FileRoot::Opfs, &crystal_data_path(id)).await {
1149	return Ok(String::from_utf8_lossy(&bytes).to_string());
1150	}
1151	if let Some((n, json)) = res!(newest_data_version(id).await) {
1152	console_log(&fmt!(
1153	"Diamond '{}' has no crystal.json; read version {} instead.", id, n));
1154	return Ok(json);
1155	}
1156	// The markdown a migration has not reached, or could not finish. Converted rather than
1157	// returned as it stands, because every caller above this now reads data.
1158	if let Ok(bytes) = opfs::read_file(FileRoot::Opfs, &crystal_legacy_path(id)).await {
1159	console_log(&fmt!(
1160	"Diamond '{}' still has a markdown crystal; it is read as data without being \
1161	converted on disk.", id));
1162	let md = String::from_utf8_lossy(&bytes).to_string();
1163	return Ok(crate::tools::crystal_from_markdown(&md).to_json());
1164	}
1165	if let Some((n, md)) = res!(newest_legacy_version(id).await) {
1166	console_log(&fmt!(
1167	"Diamond '{}' has no crystal at all; markdown version {} is read as data instead.",
1168	id, n));
1169	return Ok(crate::tools::crystal_from_markdown(&md).to_json());
1170	}
1171	console_log(&fmt!(
1172	"Diamond '{}' has no crystal and no version to fall back on; it opens empty.", id));
1173	Ok(String::new())
1174	}
1175
1176	/// Read a Diamond's current page, or empty when it has none.
1177	///
1178	/// Empty is an ordinary answer and not a failure: a Diamond created before pages existed has no
1179	/// `crystal.html`, and one whose page was reset has whatever the caller supplies instead. **Rust
1180	/// never sees the default page** -- it is a JS const, so the protocol and the page that speaks it
1181	/// live in one file -- so this reports the absence and the caller fills it.
1182	///
1183	/// The snapshots back it up exactly as they back the data up, through the walk in
1184	/// [`read_version_page`], so a page lost from its own file is recovered from the last version
1185	/// that changed it.
1186	pub async fn read_crystal_page(id: &str) -> Outcome<String> {
1187	if let Ok(bytes) = opfs::read_file(FileRoot::Opfs, &crystal_page_path(id)).await {
1188	return Ok(String::from_utf8_lossy(&bytes).to_string());
1189	}
1190	// Unreadable metadata means no page, not a throw. A Diamond that LISTS must OPEN, and the
1191	// panel opening on the built-in view beats it not opening at all.
1192	let at = match read_meta(id).await {
1193	Ok(m) => m.version,
1194	Err(_) => return Ok(String::new()),
1195	};
1196	// And nor is a chain that cannot be walked. The next write mends it: a version whose parent
1197	// could not be read is recorded as a full copy, so the Diamond heals rather than staying
1198	// unopenable -- see [`write_snapshot`].
1199	match read_version_page(id, at).await {
1200	Ok(page) => Ok(page),
1201	Err(e) => {
1202	console_log(&fmt!(
1203	"Diamond '{}' has no page file and its snapshots at version {} could not be \
1204	rebuilt: {}. It opens on the built-in page.", id, at, e));
1205	Ok(String::new())
1206	},
1207	}
1208	}
1209
1210	/// The page a Diamond has on disk right now, with no fallback of any kind.
1211	///
1212	/// [`read_crystal_page`] reaches for a snapshot when the file is not there, which is right for a
1213	/// reader and wrong for [`snapshot`]: a recovered page is not a page the user changed, and
1214	/// treating it as one would write a fresh page snapshot at a version where nothing moved.
1215	async fn page_on_disk(id: &str) -> String {
1216	match opfs::read_file(FileRoot::Opfs, &crystal_page_path(id)).await {
1217	Ok(bytes) => String::from_utf8_lossy(&bytes).to_string(),
1218	Err(_) => String::new(),
1219	}
1220	}
1221
1222	/// The newest pre-migration snapshot a Diamond holds, `versions/NNNN.md`, with its text.
1223	///
1224	/// The numbering is zero-padded and monotonic, so the highest that PARSES is the newest.
1225	async fn newest_legacy_version(id: &str) -> Outcome<Option<(u64, String)>> {
1226	let n = match snapshot_versions(id, ".md").await.into_iter().max() {
1227	Some(n) => n,
1228	None => return Ok(None),
1229	};
1230	let path = fmt!("{}/{:04}.md", versions_dir(id), n);
1231	let bytes = res!(opfs::read_file(FileRoot::Opfs, &path).await);
1232	Ok(Some((n, String::from_utf8_lossy(&bytes).to_string())))
1233	}
1234
1235	/// The newest data version a Diamond can actually REBUILD, with its text.
1236	///
1237	/// Descending rather than the highest alone, because this is the store's own redundancy and is
1238	/// reached only when `crystal.json` is already gone. A Diamond whose newest chain is broken is
1239	/// precisely the case the fallback exists for, and stopping at it would hand an agent an empty
1240	/// crystal to write over work it never saw.
1241	async fn newest_data_version(id: &str) -> Outcome<Option<(u64, String)>> {
1242	let snaps = snapshot_chain(id, DATA_KEYFRAME_EXT, DATA_PATCH_EXT).await;
1243	let mut ns: Vec<u64> = snaps.iter().map(\|(n, _)\| *n).collect();
1244	ns.sort_unstable();
1245	for n in ns.into_iter().rev() {
1246	let chain = match diamond_delta::plan_at(&snaps, n) {
1247	Ok(c) => c,
1248	Err(_) => continue,
1249	};
1250	if let Ok(bytes) = follow(id, &chain, DATA_KEYFRAME_EXT, DATA_PATCH_EXT).await {
1251	return Ok(Some((n, String::from_utf8_lossy(&bytes).to_string())));
1252	}
1253	}
1254	Ok(None)
1255	}
1256
1257	/// Write one version's snapshot of one file, and prove it before the version is allowed to stand.
1258	///
1259	/// This is what makes it impossible to record a delta that cannot be reconstructed. Three
1260	/// gates, in this order, and the last is the only one that has seen the disk:
1261	///
1262	/// 1. [`crate::diamond_delta::record`] returns a patch only from
1263	/// [`oxedyne_fe2o3_ore::diff::make_patch`], which decodes and applies what it has just encoded
1264	/// and refuses to hand back anything whose reconstruction is not the bytes it was given.
1265	/// 2. The patch is written, then READ BACK OFF THE DISK and applied to the parent in hand. The
1266	/// version stands only if THAT gives the bytes it was told to record, so a short write, a
1267	/// truncated file or a storage layer that returned success without storing anything is caught
1268	/// here rather than by the person who wanted the version back.
1269	/// 3. A full copy is read back and compared as well, which is the base case the whole chain rests
1270	/// on: every version is a keyframe plus patches each proved against the one under it, so if
1271	/// the base holds and each step holds, the version holds.
1272	///
1273	/// Every failure ends in the same place -- the full copy the store wrote before this existed --
1274	/// so the cost of any fault in the diff, the encoding, the decoding or the write is space, and
1275	/// never history. A full copy that will not read back is the one thing there is no fallback
1276	/// from, and it is an error rather than a silently missing version.
1277	///
1278	/// # Arguments
1279	/// * `parent` - The file as at the snapshot before this one, or `None` where there is none or it
1280	/// could not be rebuilt. `None` forces the full copy.
1281	/// * `want` - The file as this version holds it.
1282	/// * `snaps` - Every snapshot this file already has, which is what says whether a keyframe is due.
1283	async fn write_snapshot(
1284	id: &str,
1285	version: u64,
1286	parent: Option<&str>,
1287	want: &str,
1288	snaps: &[(u64, Snap)],
1289	kf_ext: &str,
1290	patch_ext: &str,
1291	)
1292	-> Outcome<Snap>
1293	{
1294	let rec = diamond_delta::record(parent.map(\|p\| p.as_bytes()), want.as_bytes(), snaps);
1295	if let diamond_delta::Recorded::Patch(p) = &rec {
1296	let at = snapshot_path(id, version, patch_ext);
1297	res!(opfs::write_file(FileRoot::Opfs, &at, p).await);
1298	let proved = match (opfs::read_file(FileRoot::Opfs, &at).await, parent) {
1299	(Ok(back), Some(par)) => match diff::apply_patch(par.as_bytes(), &back) {
1300	Ok(got) => got == want.as_bytes(),
1301	Err(_) => false,
1302	},
1303	_ => false,
1304	};
1305	if proved {
1306	return Ok(Snap::Patch);
1307	}
1308	// Taken away before the full copy is written, so no version is ever left holding two
1309	// snapshots for a reader to choose between.
1310	let _ = opfs::delete_entry(FileRoot::Opfs, &at, false).await;
1311	console_log(&fmt!(
1312	"Diamond '{}' version {}: the '{}' just written does not read back as the version it \
1313	records, so a full copy is written instead.", id, version, patch_ext));
1314	}
1315	let kf_at = snapshot_path(id, version, kf_ext);
1316	res!(opfs::write_file(FileRoot::Opfs, &kf_at, want.as_bytes()).await);
1317	let back = res!(opfs::read_file(FileRoot::Opfs, &kf_at).await);
1318	if back != want.as_bytes() {
1319	return Err(err!(
1320	"Diamond '{}' version {}: '{}' reads back as {} bytes and not the {} it was given, \
1321	so the version is not recorded.", id, version, kf_at, back.len(), want.len();
1322	Invalid, Data, Mismatch));
1323	}
1324	Ok(Snap::Keyframe)
1325	}
1326
1327	/// The memory as at `version`, or `None` with a console line where it cannot be rebuilt.
1328	///
1329	/// A parent that cannot be read is not a reason to refuse the write in front of the user. It is
1330	/// a reason to record this version as a full copy, which is both the safe answer and the one that
1331	/// mends the Diamond: the version after it has a keyframe to build on again.
1332	async fn parent_data(id: &str, version: u64, snaps: &[(u64, Snap)]) -> Option<String> {
1333	let chain = match diamond_delta::plan_at(snaps, version) {
1334	Ok(c) => c,
1335	Err(_) => return None, // no snapshot at all, which is an ordinary new Diamond
1336	};
1337	match follow(id, &chain, DATA_KEYFRAME_EXT, DATA_PATCH_EXT).await {
1338	Ok(bytes) => Some(String::from_utf8_lossy(&bytes).to_string()),
1339	Err(e) => {
1340	console_log(&fmt!(
1341	"Diamond '{}': the memory at version {} could not be rebuilt ({}), so the next \
1342	version records a full copy of it.", id, version, e));
1343	None
1344	},
1345	}
1346	}
1347
1348	/// Snapshot a new crystal version and return its number.
1349	///
1350	/// The two files are snapshotted on different rules, and that asymmetry is the design. The
1351	/// data is written at every version, so the history is complete without a walk. The page is
1352	/// written only where its bytes differ from the page as at the PARENT version -- not from the
1353	/// file on disk, which the daimon may already have overwritten during the turn being recorded.
1354	/// Most edits do not touch the page, and snapshotting it at every version would multiply the one
1355	/// file in a Diamond that nothing folds and nothing reduces.
1356	///
1357	/// Each half is written as splices where that is smaller, and the delta costs no read. Both
1358	/// parents are read here anyway: the data's because a version is recorded against it, the page's
1359	/// because the boolean deciding whether the page moved at all is a comparison with it. This is
1360	/// the funnel every write comes through -- `write_crystal_data`, `write_crystal_page`,
1361	/// `write_crystal_both`, `record_steer`, `record_model_change` and the fold -- so putting the
1362	/// delta log here reaches all of them and reaches nothing twice.
1363	///
1364	/// The other door on the two ceilings. `Tool::FileWrite` and `Tool::FileEdit` catch a daimon
1365	/// growing either file past its cap; this catches a hand edit and a fold, which reach the files
1366	/// through the store instead and would otherwise walk straight past the rule.
1367	///
1368	/// # Arguments
1369	/// * `id` - The Diamond.
1370	/// * `data` - The crystal data this version holds.
1371	/// * `page` - The page this version holds, or `None` for whatever is on disk -- which is what a
1372	/// turn that edited the page through the file tools leaves behind.
1373	/// * `now` - The stamp both `updated` and `touched` take.
1374	async fn snapshot(id: &str, data: &str, page: Option<&str>, now: u64) -> Outcome<u64> {
1375	let old = opfs::read_file(FileRoot::Opfs, &crystal_data_path(id)).await
1376	.map(\|b\| b.len())
1377	.unwrap_or(0);
1378	if crate::tools::crystal_write_refused(data.len(), old) {
1379	return Err(err!("{}", crate::tools::crystal_cap_message(data.len()); Invalid, Input, Size));
1380	}
1381	let disk = page_on_disk(id).await;
1382	let want: &str = page.unwrap_or(disk.as_str());
1383	if crate::tools::crystal_page_write_refused(want.len(), disk.len()) {
1384	return Err(err!("{}", crate::tools::crystal_page_cap_message(want.len());
1385	Invalid, Input, Size));
1386	}
1387
1388	let mut meta = res!(read_meta(id).await);
1389	let next = meta.version + 1;
1390
1391	// Each half's parent: what the new version is recorded against, and -- for the page -- the
1392	// answer to whether it moved at all. A parent that cannot be rebuilt is `None` rather than a
1393	// failure, which records this version as a full copy and mends the Diamond on the spot.
1394	// One directory walk read twice, because the two files live in the same directory and the
1395	// walk is the expensive half. What this adds over what the boolean already cost is the read
1396	// of the memory's chain, which the boolean never needed.
1397	let entries = version_entries(id).await;
1398	let data_snaps = classify(&entries, DATA_KEYFRAME_EXT, DATA_PATCH_EXT);
1399	let parent_data = parent_data(id, meta.version, &data_snaps).await;
1400	let page_snaps = classify(&entries, PAGE_KEYFRAME_EXT, PAGE_PATCH_EXT);
1401	let parent_page = match page_at(id, meta.version, &page_snaps).await {
1402	Ok(p) => p,
1403	Err(e) => {
1404	console_log(&fmt!(
1405	"Diamond '{}': the page at version {} could not be rebuilt ({}), so version {} \
1406	records a full copy of it.", id, meta.version, e, next));
1407	None
1408	},
1409	};
1410	// Against the parent version rather than against the file, so a page the daimon wrote itself
1411	// during the turn is still recognised as a change and still gets its snapshot.
1412	let changed = want != parent_page.clone().unwrap_or_default();
1413
1414	res!(opfs::write_file(FileRoot::Opfs, &crystal_data_path(id), data.as_bytes()).await);
1415	res!(write_snapshot(id, next, parent_data.as_deref(), data, &data_snaps,
1416	DATA_KEYFRAME_EXT, DATA_PATCH_EXT).await);
1417	if want != disk {
1418	res!(opfs::write_file(FileRoot::Opfs, &crystal_page_path(id), want.as_bytes()).await);
1419	}
1420	if changed {
1421	res!(write_snapshot(id, next, parent_page.as_deref(), want, &page_snaps,
1422	PAGE_KEYFRAME_EXT, PAGE_PATCH_EXT).await);
1423	}
1424
1425	meta.version = next;
1426	meta.updated = now;
1427	meta.touched = now; // a new crystal is both work and a change
1428	res!(write_meta(id, &meta).await);
1429	Ok(next)
1430	}
1431
1432	/// Apply a user hand-edit to the crystal's data: snapshot a new version and log an
1433	/// `edit` record.
1434	///
1435	/// The page is left exactly as it is, so an edit to the memory does not cost a page snapshot.
1436	pub async fn write_crystal_data(id: &str, json: &str) -> Outcome<()> {
1437	let now = now_ms() as u64;
1438	let parent = res!(read_meta(id).await).version;
1439	let version = res!(snapshot(id, json, None, now).await);
1440	let rec = LogRecord {
1441	id: generate_session_id(),
1442	ts: now,
1443	kind: "edit",
1444	agent: "user".to_string(),
1445	task: "edit crystal".to_string(),
1446	parent: parent as i64,
1447	version: version,
1448	delta_ref: String::new(),
1449	note: String::new(),
1450	};
1451	append_log(id, &rec).await
1452	}
1453
1454	/// Replace a Diamond's page: snapshot a new version and log an `edit` record.
1455	///
1456	/// A version of its own, sharing the one counter with the data, because a page IS the Diamond as
1457	/// the user meets it: a page edit that could not be undone would be the one change in a Diamond
1458	/// with no way back. The data is carried through unchanged and still snapshotted, which is what
1459	/// keeps `versions/NNNN.json` complete for every N.
1460	///
1461	/// # Arguments
1462	/// * `id` - The Diamond.
1463	/// * `html` - The page, self-contained; empty resets it to nothing and lets the caller's default
1464	/// stand.
1465	pub async fn write_crystal_page(id: &str, html: &str) -> Outcome<()> {
1466	let now = now_ms() as u64;
1467	let parent = res!(read_meta(id).await).version;
1468	let data = res!(read_crystal_data(id).await);
1469	let version = res!(snapshot(id, &data, Some(html), now).await);
1470	let rec = LogRecord {
1471	id: generate_session_id(),
1472	ts: now,
1473	kind: "edit",
1474	agent: "user".to_string(),
1475	task: "edit crystal page".to_string(),
1476	parent: parent as i64,
1477	version: version,
1478	delta_ref: String::new(),
1479	note: String::new(),
1480	};
1481	append_log(id, &rec).await
1482	}
1483
1484	/// Write both halves of a crystal as ONE version: one version number, one snapshot pair, one log
1485	/// record.
1486	///
1487	/// For a restore and for a backup import, which set the data and the page together and are one
1488	/// action as far as the person doing them is concerned. Doing it as
1489	/// [`write_crystal_data`] followed by [`write_crystal_page`] works and writes two versions, so the
1490	/// history shows two rows for one click -- and neither row is wrong, which is what makes it worth
1491	/// fixing rather than tolerating. The log is the record of a Diamond's discontinuities, and a
1492	/// reader counting them would count one restore as two.
1493	///
1494	/// The page still obeys the rule the other paths obey, because [`snapshot`] owns it: a page whose
1495	/// bytes match the parent version's writes no `.html` at all, so restoring a version whose page
1496	/// never differed costs nothing extra.
1497	///
1498	/// `html` is taken literally, empty included. Restoring a version from before pages existed
1499	/// means passing an empty page, and that is what the Diamond looked like -- so the page goes back
1500	/// to none and the caller's default renders. A caller that would rather keep the page it has
1501	/// should pass the page it has; this does not guess which was meant.
1502	///
1503	/// # Arguments
1504	/// * `id` - The Diamond.
1505	/// * `json` - The crystal data to put at the head.
1506	/// * `html` - The page to put at the head; empty leaves the Diamond with no page of its own.
1507	pub async fn write_crystal_both(id: &str, json: &str, html: &str) -> Outcome<()> {
1508	let now = now_ms() as u64;
1509	let parent = res!(read_meta(id).await).version;
1510	let version = res!(snapshot(id, json, Some(html), now).await);
1511	let rec = LogRecord {
1512	id: generate_session_id(),
1513	ts: now,
1514	kind: "edit",
1515	agent: "user".to_string(),
1516	task: "edit crystal and page".to_string(),
1517	parent: parent as i64,
1518	version: version,
1519	delta_ref: String::new(),
1520	note: String::new(),
1521	};
1522	append_log(id, &rec).await
1523	}
1524
1525	/// Record that this Diamond's daimon changed model, in the crystal's own history.
1526	///
1527	/// A Diamond's primary model may be changed at any time, and because the daimon is
1528	/// meant to be persistent the change ends one daimon and starts another. That is a
1529	/// discontinuity in the Diamond, so it is written where the Diamond's other
1530	/// discontinuities are written rather than left as a silent flip of a browser setting.
1531	///
1532	/// The crystal is snapshotted UNCHANGED. There is nothing to edit -- the crystal is
1533	/// what the old daimon left and what the new one inherits -- and the version exists so
1534	/// that "what did this Diamond look like when it was still on the old model" is a
1535	/// question with an answer.
1536	///
1537	/// # Arguments
1538	/// * `id` - The Diamond.
1539	/// * `note` - What changed, in the user's own language, for the history row to show.
1540	pub async fn record_model_change(id: &str, note: &str) -> Outcome<()> {
1541	let now = now_ms() as u64;
1542	let meta = res!(read_meta(id).await);
1543	let parent = meta.version;
1544	let crystal = res!(read_crystal_data(id).await);
1545	let version = res!(snapshot(id, &crystal, None, now).await);
1546	let rec = LogRecord {
1547	id: generate_session_id(),
1548	ts: now,
1549	kind: "model",
1550	agent: "user".to_string(),
1551	task: "change model".to_string(),
1552	parent: parent as i64,
1553	version: version,
1554	delta_ref: String::new(),
1555	note: note.to_string(),
1556	};
1557	append_log(id, &rec).await
1558	}
1559
1560	/// Record a crystal change made by the crystal agent (a steer that edited
1561	/// `crystal.json`, or `crystal.html`, or both): snapshot a version and log an `edit` record whose
1562	/// task is the instruction. Called by [`crate::wasm::app`] after the agent turn,
1563	/// only when the crystal actually changed.
1564	///
1565	/// The page is not an argument, because the turn has already written it: [`snapshot`] takes
1566	/// whatever is on disk and compares it with the parent version, which is how a turn that changed
1567	/// only the page still earns a page snapshot.
1568	pub async fn record_steer(id: &str, json: &str, instruction: &str) -> Outcome<()> {
1569	let now = now_ms() as u64;
1570	let parent = res!(read_meta(id).await).version;
1571	let version = res!(snapshot(id, json, None, now).await);
1572	let rec = LogRecord {
1573	id: generate_session_id(),
1574	ts: now,
1575	kind: "edit",
1576	agent: "crystal-agent".to_string(),
1577	task: instruction.to_string(),
1578	parent: parent as i64,
1579	version: version,
1580	delta_ref: String::new(),
1581	note: String::new(),
1582	};
1583	append_log(id, &rec).await
1584	}
1585
1586	/// Apply a confirmed fold: write the new crystal, snapshot a version, store
1587	/// the raw delta under `.daimond/deltas/`, and append a `fold` record that
1588	/// references the stored delta. Advisory-fold discipline: this runs only
1589	/// after the user accepts the proposed crystal; the raw delta is always
1590	/// retained.
1591	pub async fn fold_apply(id: &str, new_crystal: &str, delta: &str, note: &str) -> Outcome<()> {
1592	let now = now_ms() as u64;
1593	let parent = res!(read_meta(id).await).version;
1594	let version = res!(snapshot(id, new_crystal, None, now).await);
1595
1596	// Retain the raw delta, referenced by the log record.
1597	let dref = delta_path(id, version);
1598	res!(opfs::write_file(FileRoot::Opfs, &dref, delta.as_bytes()).await);
1599
1600	let rec = LogRecord {
1601	id: generate_session_id(),
1602	ts: now,
1603	kind: "fold",
1604	agent: "reducer".to_string(),
1605	task: "fold delta".to_string(),
1606	parent: parent as i64,
1607	version: version,
1608	delta_ref: dref,
1609	note: note.to_string(),
1610	};
1611	append_log(id, &rec).await
1612	}
1613
1614	/// Read a Diamond's log as a JSON array of records (each stored line is
1615	/// already a JSON object).
1616	pub async fn log_read(id: &str) -> Outcome<String> {
1617	let path = log_path(id);
1618	let bytes = match opfs::exists(FileRoot::Opfs, &path).await {
1619	Ok(true) => res!(opfs::read_file(FileRoot::Opfs, &path).await),
1620	_ => return Ok("[]".to_string()),
1621	};
1622	let text = String::from_utf8_lossy(&bytes);
1623	let lines: Vec<&str> = text.lines().filter(\|l\| !l.trim().is_empty()).collect();
1624	Ok(fmt!("[{}]", lines.join(",")))
1625	}
1626
1627
1628	// ┌───────────────────────────────────────────────────────────────┐
1629	// │ Links │
1630	// └───────────────────────────────────────────────────────────────┘
1631
1632	/// A Diamond's link sidecar, `diamonds/<id>/.daimond/links.jsonl`.
1633	///
1634	/// It sits beside the log rather than inside `crystal.json` for two reasons. A
1635	/// fold rewrites the crystal wholesale -- the reducer is asked for the new crystal
1636	/// and returns the whole of it -- so anything structural kept in there is
1637	/// at a model's mercy on every fold. And the crystal is handed to the conductor
1638	/// and to every worker it dispatches, so a growing list of links would be paid
1639	/// for in tokens on every turn, by agents that have the file tools anyway.
1640	fn links_path(id: &str) -> String {
1641	fmt!("{}/{}/{}/links.jsonl", ROOT_DIR, id, STORE_DIR)
1642	}
1643
1644	/// Read one Diamond's links. A missing sidecar is no links, not a failure.
1645	pub async fn read_links(id: &str) -> Outcome<Vec<Link>> {
1646	let path = links_path(id);
1647	if !res!(opfs::exists(FileRoot::Opfs, &path).await) {
1648	return Ok(Vec::new());
1649	}
1650	let bytes = res!(opfs::read_file(FileRoot::Opfs, &path).await);
1651	let text = String::from_utf8_lossy(&bytes).to_string();
1652
1653	// A sidecar written before the rename names its ends `facet:<id>` -- what a
1654	// Diamond was called when the link substrate shipped. The
1655	// substrate keeps an unknown kind rather than refusing it, so those links
1656	// would survive -- but they would survive pointing at a kind nothing
1657	// resolves any more, which is a link that renders as a dead end rather than
1658	// as the Diamond it means. Rewriting on read is enough: the file is
1659	// rewritten whenever a link is added or removed, and until then the
1660	// in-memory view is already correct.
1661	let fixed = fix_legacy_kinds(&text);
1662	if fixed != text {
1663	res!(opfs::write_file(FileRoot::Opfs, &path, fixed.as_bytes()).await);
1664	}
1665	Ok(parse_links(&fixed))
1666	}
1667
1668	/// Write one Diamond's links, replacing the sidecar.
1669	async fn write_links_for(id: &str, links: &[Link]) -> Outcome<()> {
1670	opfs::write_file(FileRoot::Opfs, &links_path(id), write_links(links).as_bytes()).await
1671	}
1672
1673	/// Assert a link from one node to another, and return its id.
1674	///
1675	/// The record is stored once, on the Diamond named by `from` when that end is a
1676	/// Diamond, and otherwise on `owner`. It is never written twice: a link is found
1677	/// from either end by [`links_touching`], which is what makes the graph two-way
1678	/// without a second copy to keep consistent.
1679	///
1680	/// # Arguments
1681	/// * `owner` - The Diamond whose sidecar holds the record.
1682	/// * `from` - The end the link is asserted from, as `kind:rest`.
1683	/// * `to` - The end it points at, as `kind:rest`.
1684	/// * `rel` - What kind of relation it is; may be empty.
1685	/// * `note` - A free sentence about it; may be empty.
1686	/// * `by` - Who asserted it: `user`, or `agent:<name>`.
1687	pub async fn add_link(
1688	owner: &str,
1689	from: &str,
1690	to: &str,
1691	rel: &str,
1692	note: &str,
1693	by: &str,
1694	)
1695	-> Outcome<String>
1696	{
1697	let from_node = match Node::parse(from) {
1698	Some(n) => n,
1699	None => return Err(err!("'{}' is not a kind:rest reference.", from; Invalid, Input)),
1700	};
1701	let to_node = match Node::parse(to) {
1702	Some(n) => n,
1703	None => return Err(err!("'{}' is not a kind:rest reference.", to; Invalid, Input)),
1704	};
1705	// A link from a thing to itself says nothing, and would draw a loop on
1706	// every view that ever renders this.
1707	if from_node == to_node {
1708	return Err(err!("A link joins two different things."; Invalid, Input));
1709	}
1710	let link = Link {
1711	id: generate_session_id(),
1712	ts: now_ms() as u64,
1713	from: from_node,
1714	to: to_node,
1715	rel: normalise_rel(rel),
1716	note: normalise_note(note),
1717	by: if by.trim().is_empty() { fmt!("user") } else { by.trim().to_string() },
1718	};
1719	let id = link.id.clone();
1720	let mut links = res!(read_links(owner).await);
1721	links.push(link);
1722	res!(write_links_for(owner, &links).await);
1723	// The sidecar rides inside the owner's directory, so a link is part of what
1724	// that Diamond IS, and the merge carries the directory whole. Without the
1725	// stamp the new link would not travel, and the other device's copy would
1726	// eventually come back over it carrying the links it had instead.
1727	touch_after_link(owner).await;
1728	Ok(id)
1729	}
1730
1731	/// Whether a Diamond is actually here, judged by the one file every Diamond has.
1732	///
1733	/// Written for the link tools, and needed because they let something OTHER than the page
1734	/// choose the owner. Every earlier caller of [`add_link`] passed an id it had just read off
1735	/// the rail; a model passes a string it wrote, and a mistyped one would have a sidecar
1736	/// written for it -- which creates the directory, and [`all_links`] walks directories rather
1737	/// than the rail, so the graph would gain links belonging to a Diamond nothing lists. That
1738	/// is the same hazard [`union_links_from`] guards against, arriving from the other side.
1739	pub async fn diamond_exists(id: &str) -> bool {
1740	if id.trim().is_empty() {
1741	return false;
1742	}
1743	opfs::exists(FileRoot::Opfs, &meta_path(id)).await.unwrap_or(false)
1744	}
1745
1746	/// Revise the relation and note of a link already in a Diamond's sidecar.
1747	/// Returns whether anything moved.
1748	///
1749	/// The store had `add_link` and `remove_link` and nothing between them, so every
1750	/// surface that let a person correct a relation did it by deleting the record and
1751	/// asserting a fresh one -- a new id and a new `ts`. That loses the one fact
1752	/// nothing else holds: when the two things were FIRST said to be related. A
1753	/// relation is a judgement about a joining that already existed, and refining the
1754	/// judgement is not a new joining. [`update_link_in`] therefore edits the record
1755	/// in place and this writes it back.
1756	///
1757	/// The ends are not revisable: a link between two OTHER things is a new claim and
1758	/// costs a new record, which [`add_link`] already makes.
1759	///
1760	/// Nothing is written when nothing moved, and that is load-bearing rather than an
1761	/// optimisation. A write stamps the Diamond, the merge reads that stamp, and a
1762	/// no-op that stamped would make this device the fresher copy for having done
1763	/// nothing -- carrying its whole directory over a real edit made elsewhere.
1764	///
1765	/// A revision does not travel by [`union_links_from`]. The union keys on the
1766	/// id and keeps the copy already held, precisely so a link is never merged field
1767	/// by field; what carries a revision is the stamp, and the wholesale merge that
1768	/// reads it -- exactly as for [`remove_link`].
1769	///
1770	/// # Arguments
1771	/// * `owner` - The Diamond whose sidecar holds the record.
1772	/// * `link_id` - The link to revise.
1773	/// * `rel` - The relation it should now carry; may be empty.
1774	/// * `note` - The note it should now carry; may be empty.
1775	pub async fn update_link(owner: &str, link_id: &str, rel: &str, note: &str) -> Outcome<bool> {
1776	let mut links = res!(read_links(owner).await);
1777	if !update_link_in(&mut links, link_id, rel, note) {
1778	return Ok(false);
1779	}
1780	res!(write_links_for(owner, &links).await);
1781	touch_after_link(owner).await; // the sidecar changed; see [`add_link`]
1782	Ok(true)
1783	}
1784
1785	/// Remove a link from a Diamond's sidecar. Returns whether one went.
1786	pub async fn remove_link(owner: &str, link_id: &str) -> Outcome<bool> {
1787	let links = res!(read_links(owner).await);
1788	let kept: Vec<Link> = links.iter().filter(\|l\| l.id != link_id).cloned().collect();
1789	if kept.len() == links.len() {
1790	return Ok(false);
1791	}
1792	res!(write_links_for(owner, &kept).await);
1793	touch_after_link(owner).await; // the sidecar changed; see [`add_link`]
1794	Ok(true)
1795	}
1796
1797	/// Take into a Diamond's sidecar every link another device's copy of it holds
1798	/// and this one does not. True when something was written.
1799	///
1800	/// The merge carries a Diamond wholesale on the freshest copy, and refuses to
1801	/// choose when the two are equally fresh. Equally fresh with different links is
1802	/// exactly the state a build that stamped nothing when a link changed used to
1803	/// leave behind, and no wholesale choice can repair it: whichever copy is
1804	/// picked, the other's links go. A union can, because links are a set of
1805	/// records with ids, and taking both copies' records is not a judgement about
1806	/// either -- the same reasoning that lets tags be unioned (see
1807	/// [`set_tags`]).
1808	///
1809	/// It settles. Writing stamps the Diamond, so this side becomes the fresher one
1810	/// and the union travels back to be taken wholesale; an import lays the stamps
1811	/// down verbatim, so nothing bounces back again; and once the two sidecars agree
1812	/// [`union_links`] adds nothing, nothing is written and no stamp moves.
1813	///
1814	/// It cannot resurrect a deletion. [`remove_link`] stamps the Diamond, so the
1815	/// copy that lost the link is the fresher one and is taken wholesale, and this
1816	/// is reached only where neither copy is fresher. What it can repair is
1817	/// therefore only the divergence the missing stamp left behind, which is what it
1818	/// is for.
1819	///
1820	/// # Arguments
1821	/// * `owner` - The Diamond whose sidecar is being reconciled.
1822	/// * `sidecar` - The other device's copy of it, as stored text.
1823	pub async fn union_links_from(owner: &str, sidecar: &str) -> Outcome<bool> {
1824	// Another device's file, so the same fixup a read applies: a link arriving
1825	// under the old kind is the same link, and writing it down unrepaired would
1826	// put a dead end in a file this device had already cleaned.
1827	let theirs = parse_links(&fix_legacy_kinds(sidecar));
1828	if theirs.is_empty() {
1829	return Ok(false);
1830	}
1831	// A Diamond that is not here is not one to write a sidecar for. Writing
1832	// would create the directory, and [`all_links`] walks directories rather
1833	// than the rail, so the graph would gain links belonging to a Diamond
1834	// nothing lists -- and the stamp afterwards would fail anyway, there being
1835	// no metadata to move.
1836	if !res!(opfs::exists(FileRoot::Opfs, &meta_path(owner)).await) {
1837	return Ok(false);
1838	}
1839	let mine = res!(read_links(owner).await);
1840	let merged = match union_links(&mine, &theirs) {
1841	Some(m) => m,
1842	None => return Ok(false), // they agree: write nothing, stamp nothing
1843	};
1844	res!(write_links_for(owner, &merged).await);
1845	touch_after_link(owner).await;
1846	Ok(true)
1847	}
1848
1849	/// Stamp the owner of a sidecar that has just changed, best effort.
1850	///
1851	/// Best effort because the link is already written: a Diamond whose `meta.json`
1852	/// cannot be read is one whose link should still exist here, and failing the
1853	/// call after the fact would tell the caller nothing happened when something
1854	/// did. What is lost is that the link may not travel until the Diamond is
1855	/// changed again, which is the same position it was in before this existed.
1856	async fn touch_after_link(owner: &str) {
1857	if let Err(e) = touch(owner).await {
1858	console_log(&fmt!("Diamond '{}' could not be stamped after a link changed: {}", owner, e));
1859	}
1860	}
1861
1862	/// Every link touching `node`, from whichever Diamond's sidecar holds it.
1863	///
1864	/// This is the read that makes the links two-way. A record is stored once, in
1865	/// one direction, so what points AT something is found by scanning rather than
1866	/// by keeping a mirrored copy -- there is no second copy to fall out of step,
1867	/// and a link hand-written into either end's sidecar counts just the same.
1868	///
1869	/// The scan walks every Diamond, which is the same walk [`list`] already does on
1870	/// each load of the rail.
1871	pub async fn links_touching(node_ref: &str) -> Outcome<Vec<(String, Link)>> {
1872	let node = match Node::parse(node_ref) {
1873	Some(n) => n,
1874	None => return Err(err!("'{}' is not a kind:rest reference.", node_ref; Invalid, Input)),
1875	};
1876	let mut out: Vec<(String, Link)> = Vec::new();
1877	let entries = match opfs::list_dir(FileRoot::Opfs, ROOT_DIR).await {
1878	Ok(e) => e,
1879	Err(_) => return Ok(out),
1880	};
1881	for (id, is_dir, _size) in entries {
1882	if !is_dir {
1883	continue;
1884	}
1885	// One unreadable sidecar must not hide every other Diamond's links.
1886	let links = match read_links(&id).await {
1887	Ok(l) => l,
1888	Err(e) => {
1889	console_log(&fmt!("Diamond '{}' has an unreadable link sidecar: {}", id, e));
1890	continue;
1891	}
1892	};
1893	for l in links {
1894	if l.touches(&node) {
1895	out.push((id.clone(), l));
1896	}
1897	}
1898	}
1899	Ok(out)
1900	}
1901
1902	/// Every link in the store, as the JSON array the surface returns.
1903	///
1904	/// One walk of `diamonds/` answers the whole graph, where asking node by node
1905	/// would walk the store once per Diamond and read every sidecar as many times
1906	/// over. The walk is [`links_touching`]'s, with the node test dropped.
1907	///
1908	/// Each entry carries the Diamond whose sidecar holds the record, exactly as
1909	/// [`links_json`] does, so a caller can delete a link without searching for it.
1910	/// There is no `other` field: no one end was asked about, so neither end is the
1911	/// other one.
1912	pub async fn all_links() -> Outcome<String> {
1913	let entries = match opfs::list_dir(FileRoot::Opfs, ROOT_DIR).await {
1914	Ok(e) => e,
1915	Err(_) => return Ok("[]".to_string()),
1916	};
1917	let mut items: Vec<String> = Vec::new();
1918	for (id, is_dir, _size) in entries {
1919	if !is_dir {
1920	continue;
1921	}
1922	// One unreadable sidecar must not hide every other Diamond's links.
1923	let links = match read_links(&id).await {
1924	Ok(l) => l,
1925	Err(e) => {
1926	console_log(&fmt!("Diamond '{}' has an unreadable link sidecar: {}", id, e));
1927	continue;
1928	}
1929	};
1930	for l in links {
1931	items.push(fmt!(
1932	"{{\"owner\":\"{}\",\"id\":\"{}\",\"ts\":{},\"from\":\"{}\",\"to\":\"{}\",\
1933	\"rel\":\"{}\",\"note\":\"{}\",\"by\":\"{}\"}}",
1934	json_escape(&id), json_escape(&l.id), l.ts,
1935	json_escape(&l.from.to_ref()), json_escape(&l.to.to_ref()),
1936	json_escape(&l.rel), json_escape(&l.note), json_escape(&l.by),
1937	));
1938	}
1939	}
1940	Ok(fmt!("[{}]", items.join(",")))
1941	}
1942
1943	/// Every link touching `node`, as the JSON array the surface returns.
1944	///
1945	/// Each entry carries the Diamond whose sidecar holds the record, so a caller can
1946	/// delete it without searching for it again, and `other` -- the end that is not
1947	/// the one asked about -- so a view has what it draws without re-deriving the
1948	/// direction.
1949	pub async fn links_json(node_ref: &str) -> Outcome<String> {
1950	let node = match Node::parse(node_ref) {
1951	Some(n) => n,
1952	None => return Err(err!("'{}' is not a kind:rest reference.", node_ref; Invalid, Input)),
1953	};
1954	let found = res!(links_touching(node_ref).await);
1955	let items: Vec<String> = found.iter().map(\|(owner, l)\| {
1956	fmt!(
1957	"{{\"owner\":\"{}\",\"id\":\"{}\",\"ts\":{},\"from\":\"{}\",\"to\":\"{}\",\
1958	\"rel\":\"{}\",\"note\":\"{}\",\"by\":\"{}\",\"other\":\"{}\"}}",
1959	json_escape(owner), json_escape(&l.id), l.ts,
1960	json_escape(&l.from.to_ref()), json_escape(&l.to.to_ref()),
1961	json_escape(&l.rel), json_escape(&l.note), json_escape(&l.by),
1962	json_escape(&l.other(&node).map(\|n\| n.to_ref()).unwrap_or_default()),
1963	)
1964	}).collect();
1965	Ok(fmt!("[{}]", items.join(",")))
1966	}
1967
1968
1969	// ┌───────────────────────────────────────────────────────────────┐
1970	// │ Whole-directory export / import │
1971	// └───────────────────────────────────────────────────────────────┘
1972
1973	/// Whether a path from an export addresses something inside the Diamond.
1974	///
1975	/// The paths in an export were written by another device, so they are checked
1976	/// rather than trusted: a `..` component would climb out of `diamonds/<id>/`
1977	/// and land the file in some other Diamond, or beside them all.
1978	fn is_safe_rel(rel: &str) -> bool {
1979	if rel.is_empty() \|\| rel.starts_with('/') \|\| rel.contains('\\') {
1980	return false;
1981	}
1982	rel.split('/').all(\|c\| !c.is_empty() && c != "." && c != "..")
1983	}
1984
1985	/// Export a whole Diamond as JSON:
1986	/// `{"id":..,"touched":..,"files":{"<path>":"<content>",..}}`, each path
1987	/// relative to `diamonds/<id>/`.
1988	///
1989	/// Filesystem-level on purpose rather than field by field. Everything a
1990	/// Diamond is lives under its directory -- the crystal, every version
1991	/// snapshot, the metadata, the log, the retained deltas, the link sidecar -- so
1992	/// a per-Diamond file added later travels with it and nothing carrying a
1993	/// Diamond about has to learn the new file's name.
1994	///
1995	/// NOT ALL OF THEM ARE TEXT ANY MORE. A version's `.jpatch` and `.hpatch` carry two
1996	/// checksums in their header, so most are not valid UTF-8; they travel base64 in the pack's
1997	/// `binary` map, and [`crate::protocol::pack_diamond`] decides which map a file goes in by
1998	/// asking the bytes rather than the name. Both routes are lossless and
1999	/// `diamond_delta::tests::test_a_patch_survives_the_pack_a_sync_carries_it_in` holds them to it.
2000	///
2001	/// The paths come out sorted, so two exports of an unchanged Diamond are the
2002	/// same bytes and a caller comparing states sees no change where there is none.
2003	///
2004	/// `touched` -- when anything under the directory last changed -- is repeated at
2005	/// the top level, so a carrier can tell two copies apart without opening a file
2006	/// inside the pack. It is a copy of what `.daimond/meta.json` says, not a
2007	/// second source of truth: an import lays the file down verbatim and the file
2008	/// wins from then on.
2009	/// What [`export_diamond`] would weigh, WITHOUT building it.
2010	///
2011	/// The sync builds a parcel under a byte budget, and it used to find out whether
2012	/// a Diamond fitted by exporting it and measuring the result -- so every Diamond
2013	/// was materialised in full, and the ones over budget were thrown away after the
2014	/// fact. The budget capped what was SENT and not what was HELD.
2015	///
2016	/// On this machine that is invisible. On a phone with fifteen Diamonds carrying
2017	/// un-pruned version history it is the whole store in memory at once, which is
2018	/// what an iPhone's tab is killed for. `list_dir` already reports each entry's
2019	/// size, so the answer costs a directory walk and not one byte of content.
2020	///
2021	/// EVERY FILE WAS WEIGHED AS THOUGH IT TRAVELLED BASE64, four bytes for three, and most of a
2022	/// Diamond does not: valid UTF-8 goes into the pack as itself, and what JSON escaping adds to a
2023	/// page is a few per cent. Measured, that over-estimate cost real syncs -- thirteen Diamonds at
2024	/// the page ceiling with five edits each were admitted five where the pack itself admits seven, so
2025	/// two were refused a parcel they would have fitted and the user was told they had been left
2026	/// behind. [`crate::protocol::packed_weight`] weighs each file by what its kind actually costs,
2027	/// and keeps the heavy figure for JSON, for the log and for anything unrecognised.
2028	///
2029	/// It is an estimate rather than a bound, and the direction it has to be right about is a
2030	/// REFUSAL: a Diamond this says will not fit is never built, so that answer has to hold, while one
2031	/// it lets through is weighed again exactly against the pack that travels.
2032	pub async fn export_size(id: &str) -> Outcome<u64> {
2033	let root = diamond_dir(id);
2034	if !res!(opfs::exists(FileRoot::Opfs, &root).await) {
2035	return Ok(0);
2036	}
2037	let mut total: u64 = 0;
2038	let mut todo: Vec<String> = vec![String::new()];
2039	while let Some(rel) = todo.pop() {
2040	let dir = if rel.is_empty() { root.clone() } else { fmt!("{}/{}", root, rel) };
2041	let entries = match opfs::list_dir(FileRoot::Opfs, &dir).await {
2042	Ok(e) => e,
2043	Err(_) => continue,
2044	};
2045	for (name, is_dir, size) in entries {
2046	let child = if rel.is_empty() { name.clone() } else { fmt!("{}/{}", rel, name) };
2047	if is_dir {
2048	todo.push(child);
2049	} else {
2050	// The path travels in the envelope too, and a Diamond with many version files
2051	// carries a lot of path, so `packed_weight` counts it and the entry's own
2052	// punctuation as well as the content.
2053	total = total.saturating_add(
2054	crate::protocol::packed_weight(&child, size));
2055	}
2056	}
2057	}
2058	Ok(total)
2059	}
2060
2061	pub async fn export_diamond(id: &str) -> Outcome<String> {
2062	let files = res!(diamond_files(id).await);
2063	// A Diamond with no readable metadata still exports; it simply carries no
2064	// stamp, and a carrier falls back to whatever the pack itself says.
2065	let touched = read_meta(id).await.map(\|m\| m.touched).unwrap_or(0);
2066	Ok(crate::protocol::pack_diamond(id, touched, &files))
2067	}
2068
2069	/// Every file under `diamonds/<id>/`, by its path relative to it.
2070	///
2071	/// Bytes, not text. What each file IS, is decided by [`crate::protocol::pack_diamond`], which is
2072	/// the one place that knows the pack's shape and the one place a test can reach.
2073	async fn diamond_files(id: &str) -> Outcome<Vec<(String, Vec<u8>)>> {
2074	let root = diamond_dir(id);
2075	if !res!(opfs::exists(FileRoot::Opfs, &root).await) {
2076	return Err(err!("There is no Diamond '{}' to export.", id; Missing, Data));
2077	}
2078	// Recursion is spelled out with an explicit stack: an `async fn` cannot
2079	// recurse without boxing its future (as `opfs::copy_dir` does the same).
2080	let mut files: Vec<(String, Vec<u8>)> = Vec::new();
2081	let mut todo: Vec<String> = vec![String::new()];
2082	while let Some(rel) = todo.pop() {
2083	let dir = if rel.is_empty() { root.clone() } else { fmt!("{}/{}", root, rel) };
2084	let entries = match opfs::list_dir(FileRoot::Opfs, &dir).await {
2085	Ok(e) => e,
2086	Err(_) => continue, // a directory that has gone carries nothing
2087	};
2088	for (name, is_dir, _size) in entries {
2089	let child = if rel.is_empty() { name.clone() } else { fmt!("{}/{}", rel, name) };
2090	if is_dir {
2091	todo.push(child);
2092	continue;
2093	}
2094	// One unreadable file must not lose the whole Diamond.
2095	let bytes = match opfs::read_file(FileRoot::Opfs, &fmt!("{}/{}", root, child)).await {
2096	Ok(b) => b,
2097	Err(e) => {
2098	console_log(&fmt!("Diamond '{}' has an unreadable file '{}': {}", id, child, e));
2099	continue;
2100	}
2101	};
2102	files.push((child, bytes));
2103	}
2104	}
2105	Ok(files)
2106	}
2107
2108	/// Export a Diamond's SHAPE as a template anybody can open: the page it renders through, its
2109	/// automation, and whatever a capp keeps beside itself -- and none of what has been recorded in it.
2110	///
2111	/// The line is drawn by [`crate::protocol::template_carries`], which is where the reasoning for
2112	/// each path is written and where it is tested. Unsealed, deliberately: a share is sealed to one
2113	/// named recipient's key and so cannot reach anybody without an account, which is the whole reason
2114	/// this second door exists.
2115	///
2116	/// # Arguments
2117	/// * `id` - The Diamond to take the shape of.
2118	/// * `with_conversation` - Carry everything instead, which is the door back to a complete copy.
2119	/// It is still a template, so it still opens as a NEW Diamond.
2120	pub async fn export_template(id: &str, with_conversation: bool) -> Outcome<String> {
2121	let files = res!(diamond_files(id).await);
2122	let kept = crate::protocol::template_files(&files, with_conversation);
2123	// The name has to come out of the metadata here, because the metadata itself does not travel:
2124	// a template carries the name at the top of the pack and nothing else from `.daimond/`. A
2125	// Diamond whose name cannot be read is refused rather than sent nameless -- what would arrive
2126	// is a tile with nothing on it but a cog, and the person opening it would have no way to know
2127	// what they had been given.
2128	let meta = res!(read_meta(id).await);
2129	let name = meta.name.trim().to_string();
2130	if name.is_empty() {
2131	return Err(err!(
2132	"Diamond '{}' has no name, so a template made from it would arrive with nothing to \
2133	call it. Name the Diamond and export it again.", id; Missing, Data));
2134	}
2135	Ok(crate::protocol::pack_template(id, meta.touched, &name, &kept))
2136	}
2137
2138	/// Recreate a Diamond from an [`export_diamond`] JSON, REPLACING whatever this
2139	/// device held under that id.
2140	///
2141	/// Wholesale, so that "the freshest copy wins" means something predictable: what
2142	/// arrives is the Diamond, rather than being merged into what was here. Two
2143	/// devices that edited the same Diamond between syncs therefore lose the older
2144	/// side entirely, links included, which is the accepted cost of carrying a
2145	/// directory rather than reconciling one.
2146	///
2147	/// Every file is laid down exactly as it arrived, `meta.json` and its two stamps
2148	/// included. Re-stamping on arrival would be wrong twice over: an import is not
2149	/// the user working on this device, so the rail would reorder itself on a pull;
2150	/// and a copy that stamped itself fresh on landing would be handed straight back
2151	/// as the newer one, so the two devices would take turns overwriting each other
2152	/// for ever.
2153	///
2154	/// The read and the parse both happen before anything is deleted, so a malformed
2155	/// export cannot leave the user with neither copy. The window between the delete
2156	/// and the last write remains: a failure inside it leaves the Diamond gone from
2157	/// this device, and the next pull brings it back.
2158	pub async fn import_diamond(json: &str) -> Outcome<()> {
2159	// The browser's own parser, not a second one written here. This JSON holds
2160	// whole files, and a hand-rolled scan would be a second unescaping
2161	// implementation to keep exactly in step with the first.
2162	let val = res!(js_sys::JSON::parse(json)
2163	.map_err(\|e\| err!("A Diamond export could not be parsed: {}.", js_str(&e); Invalid, Input)));
2164	let id = match js_prop(&val, "id") {
2165	Some(i) => i,
2166	None => return Err(err!("A Diamond export carries no id."; Invalid, Input)),
2167	};
2168	// The id becomes a path component, so it is checked rather than trusted.
2169	if !is_safe_rel(&id) \|\| id.contains('/') {
2170	return Err(err!("'{}' is not a Diamond id.", id; Invalid, Input, Path));
2171	}
2172	// A TEMPLATE MAY NOT COME THROUGH THIS DOOR. Everything below deletes the directory the pack
2173	// names, and a template names where it CAME FROM -- so the owner opening his own Log Life
2174	// template on this path would destroy the Log Life he made it from. `import_template` mints an
2175	// id instead. A kind this build has never heard of still lands as it always did; only the one
2176	// that is known to mean something else is refused.
2177	if crate::protocol::PackKind::of(json) == crate::protocol::PackKind::Template {
2178	return Err(err!(
2179	"That is a Diamond template, not a Diamond export. It says it came from '{}', which is \
2180	a note about where it was made and not a place to write it; open it as a template and \
2181	it becomes a new Diamond.", id; Invalid, Input));
2182	}
2183	let mut writes = res!(pack_files(&val));
2184	// An export with nothing in it would otherwise delete the Diamond it claims
2185	// to be, which is a deletion nobody asked for.
2186	if writes.is_empty() {
2187	return Err(err!("The export of Diamond '{}' holds no files.", id; Invalid, Input));
2188	}
2189
2190	// The metadata goes LAST, whatever order it arrived in. `list` admits a Diamond on its
2191	// metadata alone, so an import that fails half way with the metadata already down leaves a
2192	// Diamond that lists, opens, and throws on a crystal that never arrived. Written last, the
2193	// same failure leaves it invisible, and the next pull brings the whole of it back. The order
2194	// used to be the export's own, which sorts paths -- and `.daimond/meta.json` sorts BEFORE
2195	// `crystal.json`, so the bad case was the ordinary one.
2196	let meta_rel = fmt!("{}/meta.json", STORE_DIR);
2197	writes.sort_by_key(\|(rel, _)\| (*rel == meta_rel) as u8);
2198
2199	let dir = diamond_dir(&id);
2200	if res!(opfs::exists(FileRoot::Opfs, &dir).await) {
2201	res!(opfs::delete_entry(FileRoot::Opfs, &dir, true).await);
2202	}
2203	for (rel, body) in writes {
2204	// THE METADATA IS REBUILT, NOT COPIED. Every other file in an export is
2205	// the user's content and travels byte for byte; `meta.json` is a record
2206	// this app owns, and writing another device's copy verbatim is how a
2207	// damaged one spreads. Two of one user's Diamonds arrived carrying a
2208	// metadata file of 117 MB and 702 MB, and reading it killed their phone
2209	// (see `read_meta`) — a normaliser existed the whole time and this path
2210	// went round it.
2211	//
2212	// ONLY WHERE THERE IS DAMAGE, AND NEVER OVER A NAME IT COULD NOT READ.
2213	//
2214	// The first version of this rebuilt EVERY imported `meta.json`, healthy
2215	// or not, and it cost the user every Diamond name on their phone in one
2216	// sync: fifteen tiles with nothing on them but a cog. A repair that runs
2217	// on undamaged input is not a repair, it is a rewrite — and a rewrite
2218	// that drops what it failed to parse is data loss dressed as a fix.
2219	//
2220	// So: a file of a sane size is written through untouched, exactly as
2221	// every other file in the export is. An oversized one is rebuilt, and
2222	// even then only if the rebuild recovered a name — because a nameless
2223	// Meta means the parse did not find what it was looking for, and the
2224	// right answer to that is to keep the bytes and let `read_meta` deal with
2225	// them, not to overwrite them with blanks.
2226	let bytes = if rel == meta_rel && body.len() > META_MAX as usize {
2227	let text = String::from_utf8_lossy(&body).to_string();
2228	let rebuilt = Meta::from_json(&text);
2229	if rebuilt.name.trim().is_empty() {
2230	crate::wasm::entry::trail("META KEPT",
2231	&fmt!("{} is {}KB but its name did not parse — left as it came",
2232	id, body.len() / 1024));
2233	body
2234	} else {
2235	crate::wasm::entry::trail("META REBUILT",
2236	&fmt!("{} {}KB -> {}B", id, body.len() / 1024, rebuilt.to_json().len()));
2237	rebuilt.to_json().into_bytes()
2238	}
2239	} else {
2240	body
2241	};
2242	res!(opfs::write_file(FileRoot::Opfs, &fmt!("{}/{}", dir, rel), &bytes).await);
2243	}
2244	Ok(())
2245	}
2246
2247	/// The files a pack carries, text and base64 alike, each path checked against the Diamond it is
2248	/// landing in.
2249	///
2250	/// One reader for both doors, so an import and a template import cannot come to disagree about
2251	/// what a pack holds. A `files` entry that is not a string is skipped rather than refused, which
2252	/// is the tolerance [`crate::protocol::pack_diamond`] promises: a pack may carry things this build
2253	/// does not understand and must still lay down the files it does.
2254	fn pack_files(val: &JsValue) -> Outcome<Vec<(String, Vec<u8>)>> {
2255	let files_val = res!(js_sys::Reflect::get(val, &JsValue::from_str("files"))
2256	.map_err(\|e\| err!("A Diamond export has no files: {}.", js_str(&e); Invalid, Input)));
2257	let files: js_sys::Object = res!(files_val.dyn_into()
2258	.map_err(\|_\| err!("A Diamond export's files were not an object."; Invalid, Input)));
2259
2260	let mut writes: Vec<(String, Vec<u8>)> = Vec::new();
2261	for pair in js_sys::Object::entries(&files).iter() {
2262	let pair: js_sys::Array = match pair.dyn_into() {
2263	Ok(a) => a,
2264	Err(_) => continue,
2265	};
2266	let rel = match pair.get(0).as_string() {
2267	Some(p) => p,
2268	None => continue,
2269	};
2270	let body = match pair.get(1).as_string() {
2271	Some(c) => c,
2272	None => continue, // not a string; `files` carries only text
2273	};
2274	if !is_safe_rel(&rel) {
2275	return Err(err!("A Diamond export names '{}', which is not a path inside it.", rel;
2276	Invalid, Input, Path));
2277	}
2278	writes.push((rel, body.into_bytes()));
2279	}
2280	// The pictures, the fonts, the compiled PDFs -- everything that is not text. A pack from a build
2281	// that predates them simply has no `binary`, and lands as it always did.
2282	if let Ok(blobs) = js_sys::Reflect::get(val, &JsValue::from_str(crate::protocol::PACK_BINARY)) {
2283	if let Ok(blobs) = blobs.dyn_into::<js_sys::Object>() {
2284	for pair in js_sys::Object::entries(&blobs).iter() {
2285	let pair: js_sys::Array = match pair.dyn_into() {
2286	Ok(a) => a,
2287	Err(_) => continue,
2288	};
2289	let rel = match pair.get(0).as_string() {
2290	Some(p) => p,
2291	None => continue,
2292	};
2293	let body = match pair.get(1).as_string() {
2294	Some(c) => c,
2295	None => continue,
2296	};
2297	if !is_safe_rel(&rel) {
2298	return Err(err!(
2299	"A Diamond export names '{}', which is not a path inside it.", rel;
2300	Invalid, Input, Path));
2301	}
2302	// A file whose base64 is damaged is REFUSED rather than written as whatever decoded.
2303	// Half a picture written over a good one is the corruption this whole change exists
2304	// to remove, and it would arrive looking like a successful sync.
2305	let bytes = res!(crate::protocol::unpack_binary(&rel, &body));
2306	writes.push((rel, bytes));
2307	}
2308	}
2309	}
2310	Ok(writes)
2311	}
2312
2313	/// Open a template as a NEW Diamond, answering its id.
2314	///
2315	/// Nothing that is already here is written over, whatever the pack says. [`import_diamond`]
2316	/// takes the id from the pack and deletes that directory before rewriting it, which is right for a
2317	/// sync and catastrophic for a template: the id in a template is where it was MADE, so the person
2318	/// most likely to open a Log Life template is the one whose Log Life would be destroyed by it. The
2319	/// id is minted here instead ([`crate::protocol::fresh_id`]) and checked against the store a second
2320	/// time before a byte is written.
2321	///
2322	/// A plain Diamond export opens here too, and makes a copy rather than a replacement. That is a
2323	/// door worth leaving open -- duplicating a Diamond is a thing people want and this path cannot
2324	/// destroy anything -- and it costs nothing, since a pack that names no name has one in the
2325	/// `.daimond/meta.json` it carries.
2326	pub async fn import_template(json: &str) -> Outcome<String> {
2327	// The browser's own parser, for the reason `import_diamond` gives: this JSON holds whole files
2328	// and a hand-rolled scan would be a second unescaping implementation to keep in step.
2329	let val = res!(js_sys::JSON::parse(json)
2330	.map_err(\|e\| err!("A Diamond template could not be parsed: {}.", js_str(&e);
2331	Invalid, Input)));
2332	// Provenance only. It is never a path here, so it is not checked as one; it is used to
2333	// readdress the two files that name the Diamond they were written in.
2334	let old_id = js_prop(&val, "id").unwrap_or_default();
2335	let mut writes = res!(pack_files(&val));
2336	if writes.is_empty() {
2337	return Err(err!("A Diamond template holds no files, so there is nothing to open.";
2338	Invalid, Input));
2339	}
2340
2341	// The name, from the top of the pack where a template carries it, or out of the metadata where
2342	// a whole-Diamond export carries it instead.
2343	let mut name = js_prop(&val, crate::protocol::PACK_NAME).unwrap_or_default();
2344	if name.trim().is_empty() {
2345	let meta_rel = fmt!("{}/meta.json", STORE_DIR);
2346	if let Some((_, body)) = writes.iter().find(\|(rel, _)\| *rel == meta_rel) {
2347	name = Meta::from_json(&String::from_utf8_lossy(body)).name;
2348	}
2349	}
2350	let name = name.trim().to_string();
2351	if name.is_empty() {
2352	return Err(err!("A Diamond template carries nothing to call the Diamond it opens as.";
2353	Missing, Input));
2354	}
2355
2356	// Every id the store holds, so the mint has something to avoid. A root that cannot be listed is
2357	// a store with no Diamonds in it yet, which is the ordinary state on a device's first run.
2358	let taken: Vec<String> = match opfs::list_dir(FileRoot::Opfs, ROOT_DIR).await {
2359	Ok(entries) => entries.into_iter()
2360	.filter(\|(_, is_dir, _)\| *is_dir)
2361	.map(\|(name, _, _)\| name)
2362	.collect(),
2363	Err(_) => Vec::new(),
2364	};
2365	let new_id = res!(crate::protocol::fresh_id(&taken));
2366	// ASKED OF THE STORE, not of the listing. The listing is a moment old and the mint is a clock;
2367	// this is the check that has to be true, and it costs one lookup.
2368	if res!(opfs::exists(FileRoot::Opfs, &diamond_dir(&new_id)).await) {
2369	return Err(err!(
2370	"A template was to open as Diamond '{}' and there is already one there, so nothing was \
2371	written.", new_id; Conflict, Data));
2372	}
2373
2374	// The skeleton first, by the same function that makes any other Diamond: an empty crystal, its
2375	// version-0 snapshot, the metadata and a `create` record. A template that carries any of those
2376	// then lands on top of them.
2377	res!(create_fresh(&name, &new_id).await);
2378
2379	// The metadata goes LAST, for the reason `import_diamond` gives: `list` admits a Diamond on its
2380	// metadata alone, so a half-written one that already has metadata lists, opens and throws.
2381	let meta_rel = fmt!("{}/meta.json", STORE_DIR);
2382	let carries_crystal = writes.iter().any(\|(rel, _)\| rel == crate::tools::CRYSTAL_DATA_FILE);
2383	writes.sort_by_key(\|(rel, _)\| (*rel == meta_rel) as u8);
2384	for (rel, body) in writes {
2385	let bytes = crate::protocol::retarget(&rel, body, &old_id, &new_id);
2386	res!(opfs::write_file(FileRoot::Opfs,
2387	&fmt!("{}/{}", diamond_dir(&new_id), rel), &bytes).await);
2388	}
2389
2390	// A CRYSTAL WITH SOMETHING IN IT, because a page without one never appears. `renderCrystal`
2391	// draws its "nothing here yet" line INSTEAD OF MOUNTING THE PAGE when the crystal is empty, so
2392	// a Diamond furnished with a capp and an empty crystal is one whose capp is invisible -- which
2393	// is what happened the first time a template that shipped no `crystal.json` was delivered.
2394	// The title is the name, which is already at the top of the pack: this seeds nothing the
2395	// template did not already say about itself.
2396	if !carries_crystal {
2397	let seed = crate::tools::CrystalData {
2398	title: name.clone(),
2399	..Default::default()
2400	}.to_json();
2401	res!(opfs::write_file(FileRoot::Opfs, &crystal_data_path(&new_id), seed.as_bytes()).await);
2402	res!(opfs::write_file(FileRoot::Opfs, &version_data_path(&new_id, 0), seed.as_bytes())
2403	.await);
2404	}
2405
2406	// AND THE METADATA IS PUT RIGHT, whichever way it arrived.
2407	//
2408	// The grants are the reason. `kits` decides what a COMMAND may touch outside the workspace, and
2409	// a template is opened by somebody who has never met the person who made it: a grant that
2410	// travelled would be a permission nobody on this device gave. A toolkit is off by default and
2411	// it stays off, so what the template wanted is a question for whoever opens it, not a fact it
2412	// brings with it. The tags go for a smaller reason -- they are the sender's filing, not the
2413	// Diamond's shape -- and both stamps say now, because a copy that has just landed here was not
2414	// worked on last year.
2415	let mut meta = res!(read_meta(&new_id).await);
2416	let now = now_ms() as u64;
2417	meta.name = name;
2418	meta.tags = Vec::new();
2419	meta.kits = Vec::new();
2420	meta.updated = now;
2421	meta.touched = now;
2422	res!(write_meta(&new_id, &meta).await);
2423
2424	Ok(new_id)
2425	}
2426
2427
2428	// ┌───────────────────────────────────────────────────────────────┐
2429	// │ Bringing home what an earlier build left in a folder │
2430	// └───────────────────────────────────────────────────────────────┘
2431
2432	/// The most one adoption run copies out of the folder in total.
2433	///
2434	/// A ceiling exists because the folder is the user's own project and nothing says what an earlier
2435	/// build put under `diamonds/` there. Copying is into OPFS, which the browser may evict wholesale
2436	/// when it fills, so an unbounded copy could cost the user their whole store to save a directory
2437	/// they can still see on disk.
2438	const ADOPT_TOTAL_MAX: u64 = 64 * 1024 * 1024;
2439
2440	/// The largest single file one adoption run copies out of the folder.
2441	const ADOPT_FILE_MAX: u64 = 8 * 1024 * 1024;
2442
2443	/// What is inserted before a clashing file's extension, so the folder's copy is kept beside the
2444	/// store's and still opens as the kind of file it is.
2445	const FROM_MACHINE: &str = ".from-machine";
2446
2447	/// What became of one file the folder was holding.
2448	enum Took {
2449	/// It was not in the store, and now it is.
2450	Copied,
2451	/// The store already had it, byte for byte, so nothing was written.
2452	Same,
2453	/// The store had it with DIFFERENT bytes. The store's copy stands and the folder's was
2454	/// written beside it, at the path carried here.
2455	Kept(String),
2456	/// Too large for the budget, and so left exactly where it is.
2457	Skipped,
2458	}
2459
2460	/// Where a clashing file's folder copy is written: `note.md` -> `note.from-machine.md`.
2461	///
2462	/// Before the extension rather than after it, so the kept copy still opens as markdown -- the user
2463	/// is being asked to compare two files, and one of them arriving as an unopenable
2464	/// `note.md.from-machine` would make that harder than it needs to be.
2465	fn beside_path(rel: &str) -> String {
2466	let (dir, leaf) = match rel.rfind('/') {
2467	Some(i) => (&rel[..i + 1], &rel[i + 1..]),
2468	None => ("", rel),
2469	};
2470	match leaf.rfind('.') {
2471	// A leading dot is the whole name of a dotfile, not an extension.
2472	Some(i) if i > 0 => fmt!("{}{}{}{}", dir, &leaf[..i], FROM_MACHINE, &leaf[i..]),
2473	_ => fmt!("{}{}{}", dir, leaf, FROM_MACHINE),
2474	}
2475	}
2476
2477	/// Whether a directory under the folder's `diamonds/` is a Diamond at all.
2478	///
2479	/// Two ways to be one, and the second is what makes a Diamond the store has never seen adoptable:
2480	/// the store already holds it under that id, or the folder's copy carries the metadata that makes
2481	/// a Diamond a Diamond. Anything else is a directory of the user's that happens to live under
2482	/// `diamonds/` -- notes, a build output, a folder they made -- and it is left alone.
2483	///
2484	/// The test is not "does it look like it might be one". Materialising a shell of a Diamond out of
2485	/// a user's own directory would put a row on the rail that opens on a `NotFoundError`, which is
2486	/// the failure this whole change is trying to stop happening.
2487	///
2488	/// # Arguments
2489	/// * `id` - The directory name under `diamonds/` in the folder.
2490	async fn is_diamond(id: &str) -> Outcome<bool> {
2491	if res!(opfs::exists(FileRoot::Opfs, &diamond_dir(id)).await) {
2492	return Ok(true);
2493	}
2494	opfs::exists(FileRoot::Machine, &meta_path(id)).await
2495	}
2496
2497	/// Take one file out of the folder and into the store, and say what that came to.
2498	///
2499	/// The store always wins a clash, per file rather than per Diamond. The folder's copy is never
2500	/// dropped and never deleted: it is written beside the store's under [`beside_path`] and named in
2501	/// the report, because the two differing copies are the user's to reconcile and we cannot know
2502	/// which they wanted.
2503	///
2504	/// Idempotent by comparison rather than by a flag. A second run finds the store's copy identical
2505	/// (or the kept copy identical) and writes nothing, which is what lets adoption run on EVERY folder
2506	/// activation for ever -- there is no moment at which we could prove every folder has been seen, so
2507	/// there is no moment at which it would be safe to stop looking.
2508	///
2509	/// # Arguments
2510	/// * `rel` - The workspace-relative path, the same on both sides.
2511	/// * `size` - What the folder says the file weighs, so the budget is checked before it is read.
2512	/// * `used` - How much this run has copied so far, added to here.
2513	async fn take_file(rel: &str, size: u64, used: &mut u64) -> Outcome<Took> {
2514	if size > ADOPT_FILE_MAX \|\| *used + size > ADOPT_TOTAL_MAX {
2515	return Ok(Took::Skipped);
2516	}
2517	let bytes = res!(opfs::read_file(FileRoot::Machine, rel).await);
2518	if !res!(opfs::exists(FileRoot::Opfs, rel).await) {
2519	res!(opfs::write_file(FileRoot::Opfs, rel, &bytes).await);
2520	*used += size;
2521	return Ok(Took::Copied);
2522	}
2523	let held = res!(opfs::read_file(FileRoot::Opfs, rel).await);
2524	if held == bytes {
2525	return Ok(Took::Same);
2526	}
2527	// Kept on an earlier run: the copy beside it already holds exactly these bytes, so this run
2528	// has nothing to add and must not make a second copy of the second copy.
2529	let beside = beside_path(rel);
2530	if res!(opfs::exists(FileRoot::Opfs, &beside).await) {
2531	let there = res!(opfs::read_file(FileRoot::Opfs, &beside).await);
2532	if there == bytes {
2533	return Ok(Took::Same);
2534	}
2535	}
2536	res!(opfs::write_file(FileRoot::Opfs, &beside, &bytes).await);
2537	*used += size;
2538	Ok(Took::Kept(beside))
2539	}
2540
2541	/// Every file the folder holds under `root`, workspace-relative, with the size the folder reports
2542	/// for it. Sorted, so a run's order does not depend on how the browser iterates.
2543	///
2544	/// A directory the folder does not have holds nothing, which is the ordinary case and not a
2545	/// failure: most folders have neither a `diamonds/` nor a `mail/` in them.
2546	///
2547	/// Recursion is spelled out with an explicit stack, as [`export_diamond`] does and for the same
2548	/// reason: an `async fn` cannot recurse without boxing its future.
2549	///
2550	/// # Arguments
2551	/// * `root` - The workspace-relative directory to walk, on the machine folder.
2552	async fn folder_files(root: &str) -> Outcome<Vec<(String, u64)>> {
2553	let mut out: Vec<(String, u64)> = Vec::new();
2554	let mut todo: Vec<String> = vec![root.to_string()];
2555	while let Some(dir) = todo.pop() {
2556	let entries = match opfs::list_dir(FileRoot::Machine, &dir).await {
2557	Ok(e) => e,
2558	Err(_) => continue, // a directory that has gone holds nothing
2559	};
2560	for (name, is_dir, size) in entries {
2561	let child = fmt!("{}/{}", dir, name);
2562	if is_dir {
2563	todo.push(child);
2564	} else {
2565	out.push((child, size));
2566	}
2567	}
2568	}
2569	out.sort_by(\|a, b\| a.0.cmp(&b.0));
2570	Ok(out)
2571	}
2572
2573	/// Bring one Diamond's files home. True when anything was actually taken.
2574	///
2575	/// The order is the correctness. The crystal is copied FIRST and `.daimond/meta.json` LAST,
2576	/// because [`list`] admits a Diamond on its metadata alone and [`read_crystal_data`] looks for the
2577	/// crystal where it should be. Metadata written first, and a run interrupted between the two,
2578	/// leaves a Diamond that lists, opens, and throws -- visible and broken. Metadata written last
2579	/// leaves a half-adopted Diamond invisible, and the next activation completes it. Nothing is
2580	/// ever deleted from the folder, so an interruption costs nothing at all.
2581	///
2582	/// For the same reason the metadata is not written when the crystal is not in the store
2583	/// afterwards: a Diamond whose crystal was too large for the budget, or unreadable, stays out of
2584	/// the rail rather than joining it broken.
2585	///
2586	/// "The crystal" is either name. A folder left by a build older than the conversion holds
2587	/// `crystal.md` and no `crystal.json`, and refusing to adopt it because the data file is absent
2588	/// would leave the user's Diamond in a directory nothing reads -- [`list`] converts it once it is
2589	/// home.
2590	///
2591	/// # Arguments
2592	/// * `id` - The Diamond.
2593	/// * `used` - The run's byte accumulator.
2594	/// * `kept` - Collects the paths where a clashing folder copy was kept.
2595	/// * `skipped` - Collects the paths this run did not take.
2596	async fn adopt_one(
2597	id: &str,
2598	used: &mut u64,
2599	kept: &mut Vec<String>,
2600	skipped: &mut Vec<String>,
2601	)
2602	-> Outcome<bool>
2603	{
2604	let files = res!(folder_files(&diamond_dir(id)).await);
2605	let meta = meta_path(id);
2606	// Both live names and the one they replaced, in the order they matter: the memory, then the
2607	// page, then whatever markdown a Diamond has not been converted from yet.
2608	let crystals = [crystal_data_path(id), crystal_page_path(id), crystal_legacy_path(id)];
2609	let mut ordered: Vec<(String, u64)> = Vec::new();
2610	for c in crystals.iter() {
2611	if let Some(f) = files.iter().find(\|(p, _)\| p == c) {
2612	ordered.push(f.clone());
2613	}
2614	}
2615	for f in &files {
2616	if crystals.contains(&f.0) \|\| f.0 == meta {
2617	continue;
2618	}
2619	ordered.push(f.clone());
2620	}
2621	let mut took_any = false;
2622	for (rel, size) in &ordered {
2623	// One unreadable file must not lose the rest of the Diamond, nor the rest of the run.
2624	match take_file(rel, *size, used).await {
2625	Ok(Took::Copied) => took_any = true,
2626	Ok(Took::Kept(path)) => { kept.push(path); took_any = true; },
2627	Ok(Took::Same) => {},
2628	Ok(Took::Skipped) => skipped.push(rel.clone()),
2629	Err(e) => {
2630	console_log(&fmt!("'{}' could not be brought home from the folder: {}", rel, e));
2631	skipped.push(rel.clone());
2632	}
2633	}
2634	}
2635	// Last, and only over a crystal that is there to be read -- in either of the two forms a
2636	// Diamond's memory can arrive in.
2637	if let Some((rel, size)) = files.iter().find(\|(p, _)\| *p == meta) {
2638	let data = res!(opfs::exists(FileRoot::Opfs, &crystal_data_path(id)).await);
2639	let legacy = res!(opfs::exists(FileRoot::Opfs, &crystal_legacy_path(id)).await);
2640	if !data && !legacy {
2641	skipped.push(rel.clone());
2642	return Ok(took_any);
2643	}
2644	match take_file(rel, *size, used).await {
2645	Ok(Took::Copied) => took_any = true,
2646	Ok(Took::Kept(path)) => { kept.push(path); took_any = true; },
2647	Ok(Took::Same) => {},
2648	Ok(Took::Skipped) => skipped.push(rel.clone()),
2649	Err(e) => {
2650	console_log(&fmt!("'{}' could not be brought home from the folder: {}", rel, e));
2651	skipped.push(rel.clone());
2652	}
2653	}
2654	}
2655	Ok(took_any)
2656	}
2657
2658	/// What became of one mail file the folder was holding.
2659	enum Brought {
2660	/// It was not in the store, and now it is.
2661	Copied,
2662	/// The store already has a file at that path, so nothing was read, written or compared.
2663	Held,
2664	/// Too large for what is left of the budget, and so left exactly where it is for a later run.
2665	Skipped,
2666	}
2667
2668	/// Take one mail file out of the folder and into the store.
2669	///
2670	/// A CLASH IS NOT RECONCILED AND NOT COPIED BESIDE, which is where this parts company with
2671	/// [`take_file`]. A Maildir name is derived from the message's UID and the mailbox generation
2672	/// (`maildirName` in `www/js/mail.js`), so a file already at that path IS that message: a second
2673	/// copy under `.from-machine` would show up as a duplicate message in the panel, hand the agent
2674	/// the same stranger's words twice, and ride in the sync parcel for ever. A draft is the same
2675	/// argument the other way round -- the store's copy is the one the user has been editing, and the
2676	/// folder's is whatever an older build last wrote.
2677	///
2678	/// The store's presence is therefore checked FIRST, before the folder's bytes are read at all, so
2679	/// the second run over a mailbox of ten thousand messages costs ten thousand lookups and not one
2680	/// byte of transfer.
2681	///
2682	/// Bytes throughout, never text: a message with a JPEG attached is not a string, and a lossy
2683	/// decode on the way through would corrupt it silently.
2684	///
2685	/// # Arguments
2686	/// * `rel` - The workspace-relative path, the same on both sides.
2687	/// * `size` - What the folder says the file weighs, so the budget is checked before it is read.
2688	/// * `used` - How much this run has copied so far, added to here.
2689	async fn take_message(rel: &str, size: u64, used: &mut u64) -> Outcome<Brought> {
2690	if size > ADOPT_FILE_MAX \|\| *used + size > ADOPT_TOTAL_MAX {
2691	return Ok(Brought::Skipped);
2692	}
2693	if res!(opfs::exists(FileRoot::Opfs, rel).await) {
2694	return Ok(Brought::Held);
2695	}
2696	let bytes = res!(opfs::read_file(FileRoot::Machine, rel).await);
2697	res!(opfs::write_file(FileRoot::Opfs, rel, &bytes).await);
2698	*used += size;
2699	Ok(Brought::Copied)
2700	}
2701
2702	/// Bring home every message and draft an earlier build left in the open folder.
2703	///
2704	/// Until `mail/` became store state (see [`crate::tools::MAIL_ROOT`]) a mailbox followed the
2705	/// workspace root, so a sync made with a folder open wrote the messages into the user's project.
2706	/// This copies them into the store, where a mailbox belongs to the account rather than to whatever
2707	/// folder happened to be open.
2708	///
2709	/// IT COPIES AND IT NEVER DELETES. A move would be tidier and it is not available here: a
2710	/// draft exists on no server and in no gateway, so an interruption or a mistake between the read
2711	/// and the delete would destroy the only copy of a message an agent prepared for its user to send.
2712	/// The worst this can leave behind is a second copy of a mailbox in a folder the user can see and
2713	/// remove themselves.
2714	///
2715	/// Three properties, each of which the shape above is what buys:
2716	///
2717	/// * Idempotent. A second run finds every file already in the store and writes nothing. It
2718	/// is not idempotent by a flag or a stamp -- there is no moment at which every folder could be
2719	/// proved to have been seen -- but by asking the store, per file, every time.
2720	/// * It never clobbers. A path the store already holds is left alone on both sides.
2721	/// * A partial run costs nothing. Nothing is deleted and no file depends on another, so an
2722	/// interruption leaves both trees readable and the next activation finishes the job -- including
2723	/// over the budget, which resets each run while the files already home are skipped for free.
2724	///
2725	/// Only the mailboxes are taken, never the whole directory, for the reason [`is_mailbox`] gives.
2726	///
2727	/// Returns how many files were copied, and the paths this run did not take.
2728	///
2729	/// # Arguments
2730	/// * `used` - The run's byte accumulator, shared with the Diamond adoption above so one activation
2731	/// has one budget.
2732	async fn bring_mail_home(used: &mut u64) -> Outcome<(usize, Vec<String>)> {
2733	let mut copied = 0usize;
2734	let mut left: Vec<String> = Vec::new();
2735	// A folder with no `mail/` in it is the ordinary case, and it is not a failure.
2736	let entries = match opfs::list_dir(FileRoot::Machine, crate::tools::MAIL_ROOT).await {
2737	Ok(e) => e,
2738	Err(_) => return Ok((0, left)),
2739	};
2740	for (name, is_dir, _size) in entries {
2741	if !is_dir \|\| !res!(is_mailbox(&name).await) {
2742	continue;
2743	}
2744	let files = res!(folder_files(&fmt!("{}/{}", crate::tools::MAIL_ROOT, name)).await);
2745	for (rel, size) in &files {
2746	// One unreadable message must not lose the rest of the mailbox, nor the rest of the
2747	// run.
2748	match take_message(rel, *size, used).await {
2749	Ok(Brought::Copied) => copied += 1,
2750	Ok(Brought::Held) => {},
2751	Ok(Brought::Skipped) => left.push(rel.clone()),
2752	Err(e) => {
2753	console_log(&fmt!(
2754	"'{}' could not be brought home from the folder: {}", rel, e));
2755	left.push(rel.clone());
2756	}
2757	}
2758	}
2759	}
2760	Ok((copied, left))
2761	}
2762
2763	/// Whether a directory under the folder's `mail/` is one of Daimond's mailboxes.
2764	///
2765	/// The mirror of [`is_diamond`], and it earns its place the same way: `mail/` is now one of
2766	/// Daimond's own roots, but a user may have had a directory of that name in their project for
2767	/// years -- an archive, a mail module, a year's correspondence -- and copying it wholesale into the
2768	/// browser's storage would be an app helping itself to somebody's files.
2769	///
2770	/// Two ways to be a mailbox, and neither guesses. The store already holds one under that name, or
2771	/// the name carries an `@`: a mailbox directory is the account's ADDRESS with the characters a
2772	/// filesystem refuses replaced (`mailDir` in `www/js/mail.js`), and an address without an `@` is
2773	/// not an address.
2774	///
2775	/// # Arguments
2776	/// * `name` - The directory name under `mail/` in the folder.
2777	async fn is_mailbox(name: &str) -> Outcome<bool> {
2778	let here = fmt!("{}/{}", crate::tools::MAIL_ROOT, name);
2779	if res!(opfs::exists(FileRoot::Opfs, &here).await) {
2780	return Ok(true);
2781	}
2782	Ok(name.contains('@'))
2783	}
2784
2785	/// Bring home every Diamond an earlier build left in the open folder, and report what was done.
2786	///
2787	/// A build before this one let Daimond's own store follow the workspace root, so a Diamond worked
2788	/// on with a folder open wrote `diamonds/<id>/...` into the user's project: outside the sync
2789	/// parcel, invisible to the panel the moment they switched back, and absent from a backup. This
2790	/// copies those files into the store.
2791	///
2792	/// Three rules, and each is a thing that could be got dangerously wrong:
2793	///
2794	/// * Nothing is ever deleted from the folder. Deleting from a user's own project to tidy up
2795	/// after our own bug is the more dangerous of the two mistakes available here, and leaving the
2796	/// copies also makes an interrupted run free to repeat.
2797	/// * The store wins a clash, and the folder's copy is kept beside it (see [`take_file`]).
2798	/// * It runs on every activation, for ever, boot reconnect included, because there is no
2799	/// moment at which every folder can be proved to have been seen. So it is silent when it finds
2800	/// nothing: the caller shows the user nothing at all when `adopted` is empty.
2801	///
2802	/// THE MAILBOX COMES HOME HERE TOO, on the same trigger and by the same three rules (see
2803	/// [`bring_mail_home`]). It is here rather than in [`list`], where the other migrations run,
2804	/// because this is the only place that is guaranteed a folder is open: everything under `mail/`
2805	/// has to be read through [`FileRoot::Machine`], which resolves to the folder or to nothing at
2806	/// all. A user who has never opened one has no mail in a folder, and this returns before looking.
2807	///
2808	/// Returns `{"folder":bool,"adopted":[{"id","name","kept":[..]}],"left":[..],"skipped":[..],
2809	/// "mail":{"copied":n,"left":[..]}}`. `folder` is false when none is open, which is not an error
2810	/// and must not be reported as one. Mail is reported under its own key rather than folded into
2811	/// `skipped`, which drives a dialog about Diamonds.
2812	pub async fn adopt_from_folder() -> Outcome<String> {
2813	if !opfs::folder_open() {
2814	return Ok(fmt!(
2815	"{{\"folder\":false,\"adopted\":[],\"left\":[],\"skipped\":[],\
2816	\"mail\":{{\"copied\":0,\"left\":[]}}}}"));
2817	}
2818	let mut adopted: Vec<(String, String, Vec<String>)> = Vec::new();
2819	let mut left: Vec<String> = Vec::new();
2820	let mut skipped: Vec<String> = Vec::new();
2821	let mut used = 0u64;
2822	// A folder with no `diamonds/` in it is the ordinary case, and it is not a failure -- and it
2823	// says nothing about whether the folder is holding a mailbox, which is why this is an empty
2824	// list to walk rather than an early return.
2825	let entries = match opfs::list_dir(FileRoot::Machine, ROOT_DIR).await {
2826	Ok(e) => e,
2827	Err(_) => Vec::new(),
2828	};
2829	for (name, is_dir, _size) in entries {
2830	let here = fmt!("{}/{}", ROOT_DIR, name);
2831	if !is_dir {
2832	left.push(here);
2833	continue;
2834	}
2835	match is_diamond(&name).await {
2836	Ok(true) => {},
2837	Ok(false) => { left.push(here); continue; },
2838	Err(e) => {
2839	console_log(&fmt!("'{}' in the folder could not be examined: {}", here, e));
2840	left.push(here);
2841	continue;
2842	}
2843	}
2844	let mut kept: Vec<String> = Vec::new();
2845	let took = match adopt_one(&name, &mut used, &mut kept, &mut skipped).await {
2846	Ok(t) => t,
2847	Err(e) => {
2848	console_log(&fmt!("Diamond '{}' could not be brought home: {}", name, e));
2849	continue;
2850	}
2851	};
2852	if !took {
2853	continue; // already home: say nothing, or every boot would announce itself
2854	}
2855	// The name the rail will show, read from the store now that the metadata is in it.
2856	let label = read_meta(&name).await.map(\|m\| m.name).unwrap_or_else(\|_\| name.clone());
2857	adopted.push((name, label, kept));
2858	}
2859	// The mailbox, on the remaining budget. A failure here is reported and does not fail the run:
2860	// the Diamonds are already home by this point, and nothing has been deleted from the folder.
2861	let (mail_copied, mail_left) = match bring_mail_home(&mut used).await {
2862	Ok(v) => v,
2863	Err(e) => {
2864	console_log(&fmt!("The mailbox in the folder could not be brought home: {}", e));
2865	(0usize, Vec::new())
2866	}
2867	};
2868	let rows: Vec<String> = adopted.iter().map(\|(id, name, kept)\| {
2869	let ks: Vec<String> = kept.iter().map(\|k\| fmt!("\"{}\"", json_escape(k))).collect();
2870	fmt!(
2871	"{{\"id\":\"{}\",\"name\":\"{}\",\"kept\":[{}]}}",
2872	json_escape(id), json_escape(name), ks.join(","),
2873	)
2874	}).collect();
2875	let quote = \|v: &[String]\| -> String {
2876	let items: Vec<String> = v.iter().map(\|s\| fmt!("\"{}\"", json_escape(s))).collect();
2877	items.join(",")
2878	};
2879	Ok(fmt!(
2880	"{{\"folder\":true,\"adopted\":[{}],\"left\":[{}],\"skipped\":[{}],\
2881	\"mail\":{{\"copied\":{},\"left\":[{}]}}}}",
2882	rows.join(","), quote(&left), quote(&skipped), mail_copied, quote(&mail_left),
2883	))
2884	}
2885
2886	/// Bring home every Diamond the open folder is holding, as the page calls it.
2887	///
2888	/// Called from `activateFolder` in `daimond.js`, which runs on every folder activation including
2889	/// the silent reconnect at boot -- so a user of yesterday's build gets their stranded Diamonds back
2890	/// on their next page load with no action at all. See [`adopt_from_folder`] for what it does and
2891	/// what it refuses to do.
2892	#[wasm_bindgen]
2893	pub async fn adopt_folder_diamonds() -> Result<String, JsValue> {
2894	adopt_from_folder().await.map_err(crate::wasm::to_js_err)
2895	}