@appsoftwareltd/etherpk-mcp 0.15.0 → 0.16.0

package/dist/main.js

@@ -627,8 +627,8 @@ var ASSET_CHUNK_PLAINTEXT_BYTES = 4194304;
 function assetChunkCount(size) {
 	return Math.max(1, Math.ceil(size / ASSET_CHUNK_PLAINTEXT_BYTES));
 }
-var DAY = 864e5;
-365 * DAY, 30 * DAY, 7 * DAY;
+var DAY$1 = 864e5;
+365 * DAY$1, 30 * DAY$1, 7 * DAY$1;
 /** Whether `text` is a short link a Sync Server opens: one of Google's share links. */
 function isShortMapLink(text) {
 	let url;
@@ -717,7 +717,7 @@ function looksLikeAgentSetupCode(value) {
 }
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.15.0",
+	version: "0.16.0",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -863,7 +863,7 @@ function fromBase64Url(text) {
 * is indistinguishable from random, so the server can tell two assets in *one* graph are
 * identical and nothing more; the secret is per graph, so nothing compares across graphs.
 */
-var INFO = "etherpk/asset-dedup/v1";
+var INFO$1 = "etherpk/asset-dedup/v1";
 /** The graph's dedup secret (32 bytes) for its newest epoch. Derive once per epoch. */
 async function deriveAssetDedupSecret(keyring) {
 	const newest = keyring.epochs.at(-1);
@@ -873,7 +873,7 @@ async function deriveAssetDedupSecret(keyring) {
 		name: "HKDF",
 		hash: "SHA-256",
 		salt: utf8(keyring.graphId),
-		info: utf8(INFO)
+		info: utf8(INFO$1)
 	}, ikm, 256);
 	return new Uint8Array(bits);
 }
@@ -1542,6 +1542,50 @@ async function openVault(envelope, key) {
 	throw new EnvelopeError(`unexpected vault envelope kind ${envelope[1] ?? "none"}`);
 }
 contextAad("settings-vault", "v1");
+//#endregion
+//#region ../client/src/lib/crypto/journal-doc-id.ts
+/**
+* The **journal document id** (ADR 0157): a [[Journal Entry]]'s document id, derived from its day,
+* so two devices that start the same day before they hear of each other write into one document
+* and the CRDT merges their text, instead of leaving two documents behind one name.
+*
+*   secret = HKDF-SHA-256(ikm = epoch 1 key, salt = graph id, info = 'etherpk/journal-doc-id/v1')
+*   id     = HMAC-SHA-256(secret, 'YYYY-MM-DD'), first 128 bits, as a version 8 UUID
+*
+* The **epoch 1** key is the input, never the newest (unlike the asset dedup token): the id must
+* not change when the graph moves to a new Graph Key epoch (ADR 0127), or a day started before a
+* rotation and the same day started after it would get two documents. Every member holds every
+* epoch, so every member derives the same id. The server sees document ids already, and without
+* the key an id is indistinguishable from a random one, so it learns no day from it.
+*/
+var INFO = "etherpk/journal-doc-id/v1";
+var DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** The graph's journal id secret (32 bytes). It never changes, so derive it once per session. */
+async function deriveJournalIdSecret(keyring) {
+	const first = keyForEpoch(keyring, 1);
+	if (!first) throw new Error("deriveJournalIdSecret: keyring has no epoch 1 key");
+	const ikm = await crypto.subtle.importKey("raw", first, "HKDF", false, ["deriveBits"]);
+	const bits = await crypto.subtle.deriveBits({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: utf8(keyring.graphId),
+		info: utf8(INFO)
+	}, ikm, 256);
+	return new Uint8Array(bits);
+}
+/** The document id of the journal entry for `day` (`YYYY-MM-DD`), under the graph's secret. */
+async function journalDocId(secret, day) {
+	if (!DAY.test(day)) throw new Error(`journalDocId: "${day}" is not a calendar day`);
+	const key = await crypto.subtle.importKey("raw", secret, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const bytes = new Uint8Array(await crypto.subtle.sign("HMAC", key, utf8(day))).slice(0, 16);
+	bytes[6] = bytes[6] & 15 | 128;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 var PAD_TO = 64;
 var LENGTH_PREFIX = 2;
 function graphNameAad(graphId) {
@@ -7910,6 +7954,12 @@ var REMOTE = Symbol("etherpk-remote");
 var CACHE_SEED = Symbol("etherpk-cache-seed");
 /** Structural lifecycle changes which must never be mistaken for a user's edit. */
 var SUPPRESSED = Symbol("etherpk-suppressed");
+/**
+* A created document's text written again as this device's own insert, so it can be sent whole
+* to a generation that never held the structs it was first written with (ADR 0157). Local, so it
+* is sent, but no undo manager tracks it.
+*/
+var RECREATED = Symbol("etherpk-recreated");
 /** Health that says the bytes are not this document's, so neither text nor emptiness is real. */
 function contentBlocked(health) {
 	return health === "key-unavailable" || health === "ciphertext-corrupt";
@@ -8002,6 +8052,14 @@ function createDocSync(deps) {
 	let pendingSnapshot;
 	/** The newest epoch an update needed that the keyring does not hold (ADR 0127). */
 	let missingEpoch;
+	/** Set by `claimCreation` until the relay acknowledges this device's first text. */
+	let createdHere = false;
+	/**
+	* Set when the relay answered `stale_generation` to text this device created or resurrected:
+	* the next catch-up page tells which generation the relay holds, and that text is then
+	* written again and sent whole into it rather than cleared.
+	*/
+	let recreating = false;
 	/** Outbox operations the relay refused as sealed under an older epoch: sealed again on `keysChanged`. */
 	const refusedAsStale = /* @__PURE__ */ new Set();
 	/** A read-back failed: the next idle uploads a fresh snapshot whatever the tail size. */
@@ -8031,6 +8089,44 @@ function createDocSync(deps) {
 		catchupActive = false;
 		catchupCompletion.resolve();
 	}
+	/**
+	* The relay holds this document at a generation that the text this device created was not
+	* written in (ADR 0157). Move to that generation, and write the text again as one insert of
+	* this device's own, so it depends on no struct the generation never held (a deterministic
+	* Journal Template's among them). The next send carries the whole state: a `resurrect` into a
+	* deleted generation, an append into one that another device started first.
+	*/
+	function recreateInto(nextGeneration, state) {
+		recreating = false;
+		documentGeneration = nextGeneration;
+		lifecycleState = state;
+		lastSeq = 0;
+		syncHealth = "healthy";
+		const content = doc.getText("content");
+		const text = content.toString();
+		if (text === "") return;
+		doc.transact(() => {
+			content.delete(0, text.length);
+			content.insert(0, text);
+		}, RECREATED);
+	}
+	/**
+	* A catch-up has reached a newer active generation than this device's copy (ADR 0157): the
+	* document was deleted, and started again, while this device was away. The copy holds the
+	* deleted generation's text, so it is cleared, never merged into the new one. The new
+	* generation never held the structs that remain, so the next send carries the whole state.
+	*/
+	function discardOlderGeneration() {
+		const content = doc.getText("content");
+		seeding = true;
+		try {
+			if (content.length > 0) doc.transact(() => content.delete(0, content.length), SUPPRESSED);
+		} finally {
+			seeding = false;
+		}
+		lastSyncedStateVector = Y.encodeStateVector(new Y.Doc());
+		lastSyncedSnapshot = Y.snapshot(doc);
+	}
 	function failCatchup(error) {
 		const reported = asError(error);
 		firstCatchupPage.reject(reported);
@@ -8138,7 +8234,8 @@ function createDocSync(deps) {
 				epochId: epoch.epochId,
 				envelope: toBase64Url(await encrypt(plaintext)),
 				stateVector: operationStateVector,
-				createdAt: now()
+				createdAt: now(),
+				...createdHere ? { creates: true } : {}
 			};
 			const state = stateSnapshot();
 			await persistTask(() => persist.enqueue(operation, state, { settledDirtyTokens }));
@@ -8506,6 +8603,7 @@ function createDocSync(deps) {
 						}
 						lastSyncedStateVector = mergeStateVectors(lastSyncedStateVector, operation.stateVector);
 						lifecycleState = "active";
+						createdHere = false;
 						updatesSinceSnapshot += 1;
 						bytesSinceSnapshot += fromBase64Url(operation.envelope).byteLength;
 						scheduleAutomaticCompaction();
@@ -8529,6 +8627,21 @@ function createDocSync(deps) {
 					try {
 						const beforeBatch = indexMutationVersion;
 						if (message.generation < documentGeneration) break;
+						if (recreating) {
+							recreateInto(message.generation, message.state);
+							if (message.state === "deleted") {
+								await saveCurrent({ indexContentChanged: true });
+								futureUpdates.clear();
+								completeCatchup();
+								break;
+							}
+						} else if (message.state === "active" && message.generation > documentGeneration && lifecycleState === "active") discardOlderGeneration();
+						if (message.state === "deleted" && message.generation === documentGeneration && (lifecycleState === "deleted" || lifecycleState === "resurrecting")) {
+							lastSeq = 0;
+							futureUpdates.clear();
+							completeCatchup();
+							break;
+						}
 						if (message.state === "deleted") {
 							documentGeneration = message.generation;
 							lifecycleState = "deleted";
@@ -8635,10 +8748,21 @@ function createDocSync(deps) {
 			await transmit(durableQueue[0]);
 		},
 		lifecycle: () => lifecycleState,
+		generation: () => documentGeneration,
+		claimCreation() {
+			createdHere = true;
+		},
 		health: () => syncHealth,
 		async staleGeneration(currentGeneration) {
 			syncHealth = "generation-stale";
-			for (const operation of durableQueue.splice(0)) await persist.discard(operation.outboxId);
+			const discarded = durableQueue.splice(0);
+			if (createdHere || discarded.some((operation) => operation.kind === "resurrect" || operation.kind === "append" && operation.creates)) {
+				recreating = true;
+				createdHere = true;
+				lastSyncedStateVector = Y.encodeStateVector(new Y.Doc());
+				lastSyncedSnapshot = void 0;
+			} else if (currentGeneration > documentGeneration && lifecycleState === "active") discardOlderGeneration();
+			for (const operation of discarded) await persist.discard(operation.outboxId);
 			queueChanged();
 			boundarySnapshots.clear();
 			documentGeneration = currentGeneration;
@@ -9720,6 +9844,14 @@ function createGraphSync(deps) {
 	const foregroundCatchups = [];
 	const backgroundCatchups = [];
 	let catchupInFlight;
+	/**
+	* The request the in-flight one's document asked for again while it was in flight. The relay
+	* may have composed the in-flight answer before whatever prompted the second request: an ack
+	* naming a sequence that another device's concurrent first write took, for one. Dropped as a
+	* duplicate, that document stayed behind for good, so it runs once more if the answer leaves
+	* the document with a gap.
+	*/
+	let catchupRepeat;
 	let resolveFirstOpen;
 	const firstOpen = new Promise((resolve) => {
 		resolveFirstOpen = resolve;
@@ -9812,7 +9944,10 @@ function createGraphSync(deps) {
 	}
 	function queueCatchup(message) {
 		if (!open) return;
-		if (catchupInFlight?.docId === message.docId && catchupInFlight.generation === message.generation && catchupInFlight.afterSeq === message.afterSeq) return;
+		if (catchupInFlight?.docId === message.docId && catchupInFlight.generation === message.generation && catchupInFlight.afterSeq === message.afterSeq) {
+			catchupRepeat = message;
+			return;
+		}
 		const removeQueued = (queue) => {
 			const index = queue.findIndex((candidate) => candidate.docId === message.docId);
 			if (index >= 0) queue.splice(index, 1);
@@ -9826,6 +9961,9 @@ function createGraphSync(deps) {
 		if (!requestId || catchupInFlight?.requestId !== requestId) return;
 		const completedDocId = catchupInFlight.docId;
 		catchupInFlight = void 0;
+		const repeat = catchupRepeat?.docId === completedDocId ? catchupRepeat : void 0;
+		catchupRepeat = void 0;
+		if (repeat && engines.get(completedDocId)?.health() === "sequence-gap") queueCatchup(repeat);
 		pumpCatchups();
 		retireEngineIfIdle(completedDocId);
 	}
@@ -10125,7 +10263,10 @@ function createGraphSync(deps) {
 				return;
 			}
 			if (message.code === "stale_generation" && message.docId && message.currentGeneration !== void 0) {
-				if (catchupInFlight?.docId === message.docId) catchupInFlight = void 0;
+				if (catchupInFlight?.docId === message.docId) {
+					catchupInFlight = void 0;
+					catchupRepeat = void 0;
+				}
 				operationAnswered(message.docId);
 				engine(message.docId).staleGeneration(message.currentGeneration);
 				pumpCatchups();
@@ -10183,6 +10324,7 @@ function createGraphSync(deps) {
 		operationsInFlight.clear();
 		operationsWaiting.clear();
 		catchupInFlight = void 0;
+		catchupRepeat = void 0;
 		foregroundCatchups.length = 0;
 		backgroundCatchups.length = 0;
 		for (const pending of watermarkRequests.values()) {
@@ -10311,6 +10453,7 @@ function createGraphSync(deps) {
 		});
 	}
 	connect();
+	let journalIdSecret;
 	return {
 		rootDoc: root.doc,
 		docSync: (docId) => engine(docId),
@@ -10367,6 +10510,10 @@ function createGraphSync(deps) {
 		compactDoc: (docId) => deps.cache.docCache(docId).compact(),
 		uploadSnapshot: (docId) => engine(docId).compact(),
 		registry: () => registryMap,
+		journalDocId(date) {
+			journalIdSecret ??= deriveJournalIdSecret(keyring());
+			return journalIdSecret.then((secret) => journalDocId(secret, date));
+		},
 		getMeta() {
 			const name = metaMap.get("name");
 			const settings = metaMap.get("settings");
@@ -10623,6 +10770,7 @@ function createGraphSync(deps) {
 			foregroundCatchups.length = 0;
 			backgroundCatchups.length = 0;
 			catchupInFlight = void 0;
+			catchupRepeat = void 0;
 			for (const pending of watermarkRequests.values()) {
 				clearTimeout(pending.timer);
 				pending.reject(/* @__PURE__ */ new Error("the graph sync session was disposed"));
@@ -14029,7 +14177,7 @@ async function publishedFence(asked, info, concept, pictures, warnings) {
 function assetHrefOf(name) {
 	return `assets/${encodeURIComponent(name)}`;
 }
-function bodyOf$1(doc) {
+function bodyOf$2(doc) {
 	return parseFrontmatter(doc.text).body;
 }
 /** Every `http(s)` resource a piece of HTML or CSS pulls in, for the report. */
@@ -14216,7 +14364,7 @@ async function publishPublication(source, publication, env, options = {}) {
 	});
 	const bodies = [...included, ...includeDocs.values()].map((d) => ({
 		doc: d,
-		body: bodyOf$1(d)
+		body: bodyOf$2(d)
 	}));
 	for (const { doc, body } of bodies) for (const fence of probe.fences(body)) {
 		const fenceKey = `${fence.lang}\n${fence.code}`;
@@ -14329,7 +14477,7 @@ async function publishPublication(source, publication, env, options = {}) {
 		progress("rendering", done++, included.length);
 		const slug = slugs.get(conceptKey$1(doc.concept));
 		scopeDiagrams(`mermaid_${slug}`);
-		const rendered = renderer.render(bodyOf$1(doc));
+		const rendered = renderer.render(bodyOf$2(doc));
 		const isHome = doc === homeDoc;
 		const page = {
 			doc,
@@ -14346,7 +14494,7 @@ async function publishPublication(source, publication, env, options = {}) {
 			if (dated.date !== void 0) page.date = dated.date;
 			take(dated.issues);
 		}
-		for (const link of linksOf(bodyOf$1(doc), resolver, doc)) report.missingLinks.push(link);
+		for (const link of linksOf(bodyOf$2(doc), resolver, doc)) report.missingLinks.push(link);
 		pages.push(page);
 		report.included.push({
 			concept: doc.concept,
@@ -14387,7 +14535,7 @@ async function publishPublication(source, publication, env, options = {}) {
 			});
 			continue;
 		}
-		const body = bodyOf$1(doc);
+		const body = bodyOf$2(doc);
 		if (cssSlots.has(slot)) {
 			const fence = renderer.fences(body).find((f) => f.lang === "css");
 			if (!fence) {
@@ -14558,7 +14706,7 @@ async function publishPublication(source, publication, env, options = {}) {
 	})));
 	const wanted = /* @__PURE__ */ new Map();
 	for (const page of pages) for (const name of page.rendered.assets) if (!wanted.has(name)) wanted.set(name, page.doc.concept);
-	for (const [, doc] of includeDocs) for (const name of renderer.render(bodyOf$1(doc)).assets) if (!wanted.has(name)) wanted.set(name, doc.concept);
+	for (const [, doc] of includeDocs) for (const name of renderer.render(bodyOf$2(doc)).assets) if (!wanted.has(name)) wanted.set(name, doc.concept);
 	let assetsDone = 0;
 	for (const [name, from] of wanted) {
 		progress("assets", assetsDone++, wanted.size);
@@ -23854,7 +24002,7 @@ function describeFilesystemSaveFailure(error, concept) {
 //#endregion
 //#region src/headless-documents.ts
 /** The document's text after its frontmatter block, and where that block ends. */
-function bodyOf(text) {
+function bodyOf$1(text) {
 	const head = frontmatterSpan(text)?.end ?? 0;
 	return {
 		head,
@@ -23869,16 +24017,16 @@ function bodyOf(text) {
 function bodyView(handle) {
 	return {
 		id: handle.id,
-		getText: () => bodyOf(handle.getText()).body,
+		getText: () => bodyOf$1(handle.getText()).body,
 		applyChange(change, origin) {
-			const { head } = bodyOf(handle.getText());
+			const { head } = bodyOf$1(handle.getText());
 			handle.applyChange({
 				from: change.from + head,
 				to: change.to + head,
 				insert: change.insert
 			}, origin);
 		},
-		subscribe: (listener) => handle.subscribe((text) => listener(bodyOf(text).body))
+		subscribe: (listener) => handle.subscribe((text) => listener(bodyOf$1(text).body))
 	};
 }
 //#endregion
@@ -24004,6 +24152,34 @@ function createBreather(now = () => performance.now()) {
 	};
 }
 //#endregion
+//#region ../client/src/lib/storage/server/duplicate-names.ts
+/** A document's text below its [[Frontmatter]] block, if it has one. */
+function bodyOf(text) {
+	return text.slice(frontmatterSpan(text)?.end ?? 0);
+}
+/**
+* The text a Merge leaves in the first document: its own text whole, then each other document's
+* text below its block, after a blank line, in the order given. Every other document's identity is
+* already the first one's, and its aliases join in the registry, so its block adds nothing.
+*
+* Always the first text followed by an addition, so the store writes it as an append: an edit made
+* meanwhile on another device anywhere in the first document is kept.
+*/
+function mergedText(texts) {
+	let merged = texts[0] ?? "";
+	for (const other of texts.slice(1)) {
+		const body = bodyOf(other).replace(/^\s+/, "");
+		if (body === "") continue;
+		if (merged.trim() === "") {
+			merged += body;
+			continue;
+		}
+		const separator = merged.endsWith("\n\n") ? "" : merged.endsWith("\n") ? "\n" : "\n\n";
+		merged += separator + body;
+	}
+	return merged;
+}
+//#endregion
 //#region ../client/src/lib/storage/server/server-document-store.ts
 /**
 * ServerDocumentStore (plan Phase 3 Task 6): the DocumentStore seam over the E2EE sync
@@ -24021,6 +24197,12 @@ function createServerDocumentStore(graph, options) {
 	const ENGINE_BATCH = 100;
 	/** Longest a cold-empty document holds its loading state waiting for first catchup. */
 	const COLD_CONTENT_TIMEOUT_MS = 15e3;
+	/**
+	* Longest a create waits, while connected, for the registry (and a journal's own document) to
+	* catch up before it checks the name again (ADR 0157). Long enough for a reconnect's first
+	* pages, short enough that a slow relay does not hold up a person who is typing.
+	*/
+	const CREATE_CONFIRM_MS = 5e3;
 	const breathe = createBreather();
 	const changeListeners = /* @__PURE__ */ new Set();
 	const docsChangedListeners = /* @__PURE__ */ new Set();
@@ -24029,6 +24211,16 @@ function createServerDocumentStore(graph, options) {
 	/** docId to the name it had when first seen renamed from elsewhere, and its latest name. */
 	const renamesFromElsewhere = /* @__PURE__ */ new Map();
 	const resurrectionClaims = /* @__PURE__ */ new Map();
+	/**
+	* Journal entries this device started before its registry had caught up (ADR 0157). A derived
+	* id can already be a registry key that another device set and then deleted while this one was
+	* away. Two concurrent sets of one Y.Map key keep one of them, and when the kept one is the
+	* deleted one, this device's entry goes too: its text would be in the document but no name
+	* would reach it. A claim sets the entry again when that happens, until the registry has
+	* caught up once with this device connected, after which a delete is someone's decision.
+	*/
+	const creationClaims = /* @__PURE__ */ new Map();
+	const stopClaimWatches = /* @__PURE__ */ new Set();
 	let disposed = false;
 	/** Whether the encrypted registry has been read to its terminal relay page this session. */
 	let registryConfirmed = false;
@@ -24114,10 +24306,21 @@ function createServerDocumentStore(graph, options) {
 	/**
 	* Every name a document answers to, to its docId. A page's own name outranks another page's
 	* alias of the same name, whatever order the registry lists them in, as the index resolves it.
+	*
+	* A name that more than one document answers to (a [[Duplicate Name]], ADR 0157) keeps the
+	* document it opened before, while that document still answers to it. The registry lists a key
+	* that arrived by sync last, so without this a duplicate arriving would move every open tab
+	* and link of the name onto the other device's document, and two devices would each open the
+	* other's. A name moves only when its document leaves it: deleted, merged or renamed away.
 	*/
-	function currentDocIds() {
+	function currentDocIds(previous) {
 		const out = /* @__PURE__ */ new Map();
-		registry.forEach((entry, docId) => out.set(conceptKey(conceptOf(entry)), docId));
+		registry.forEach((entry, docId) => {
+			const key = conceptKey(conceptOf(entry));
+			const held = out.get(key);
+			if (held !== void 0 && previous?.get(key) === held) return;
+			out.set(key, docId);
+		});
 		registry.forEach((entry, docId) => {
 			for (const alias of entry.aliases ?? []) {
 				const key = conceptKey(alias);
@@ -24156,7 +24359,7 @@ function createServerDocumentStore(graph, options) {
 			const next = currentConcepts();
 			for (const [key, concept] of known) if (!next.has(key) && !renamedAway.has(key)) removedListeners.forEach((l) => l(concept));
 			known = next;
-			docIdsByConcept = currentDocIds();
+			docIdsByConcept = currentDocIds(docIdsByConcept);
 			knownRegistry = nextRegistry;
 			docsChangedListeners.forEach((l) => l());
 			if (!restored) {
@@ -24177,6 +24380,16 @@ function createServerDocumentStore(graph, options) {
 			}
 			for (const [docId, change] of event.changes.keys) {
 				if (change.action !== "delete") continue;
+				const created = creationClaims.get(docId);
+				if (created) queueMicrotask(() => {
+					if (registry.has(docId) || !creationClaims.has(docId)) return;
+					const engine = graph.docSync(docId);
+					if (engine.lifecycle() === "deleting" || engine.doc.getText("content").length === 0) {
+						creationClaims.delete(docId);
+						return;
+					}
+					registry.set(docId, created);
+				});
 				const claimed = resurrectionClaims.get(docId);
 				if (!claimed) continue;
 				queueMicrotask(() => {
@@ -24391,7 +24604,7 @@ function createServerDocumentStore(graph, options) {
 				registryConfirmed = true;
 			}
 			known = currentConcepts();
-			docIdsByConcept = currentDocIds();
+			docIdsByConcept = currentDocIds(docIdsByConcept);
 			knownRegistry = currentRegistryIdentities();
 		},
 		listDocuments() {
@@ -24415,6 +24628,9 @@ function createServerDocumentStore(graph, options) {
 			pages.sort((a, b) => a.concept.localeCompare(b.concept));
 			return [...journals, ...pages];
 		},
+		documentIdOf(target) {
+			return docIdFor(target);
+		},
 		listIdentities() {
 			const out = [];
 			registry.forEach((entry, docId) => {
@@ -24685,26 +24901,83 @@ function createServerDocumentStore(graph, options) {
 				materialised.release();
 			}
 		},
+		async mergeDuplicates(docIds, expected, mergeOptions) {
+			const timeoutMs = mergeOptions?.timeoutMs ?? COLD_CONTENT_TIMEOUT_MS;
+			const [first, ...others] = docIds;
+			if (!first || others.length === 0 || !oneName(docIds)) return "gone";
+			if (!graph.isConnected()) return "offline";
+			if (!await confirmRegistry(timeoutMs)) return "unconfirmed";
+			const materialised = await materialise(docIds, timeoutMs);
+			try {
+				if (!oneName(docIds)) return "gone";
+				if (materialised.unconfirmed.length > 0) return "unconfirmed";
+				const texts = docIds.map((id) => graph.docSync(id).doc.getText("content").toString());
+				if (texts.some((text) => documentProtection(text).kind === "document")) return "protected";
+				if (docIds.some((id, index) => texts[index] !== expected.get(id))) return "changed";
+				const firstText = texts[0];
+				const addition = mergedText(["", ...texts.slice(1)]);
+				if (addition !== "" && !firstText.endsWith(addition)) {
+					const merged = mergedText(texts);
+					const ytext = graph.docSync(first).doc.getText("content");
+					ytext.doc.transact(() => ytext.insert(firstText.length, merged.slice(firstText.length)), STORE);
+				}
+				const firstEntry = registry.get(first);
+				const aliases = others.reduce((union, id) => mergeDocuments({
+					body: "",
+					aliases: union
+				}, {
+					body: "",
+					aliases: registry.get(id)?.aliases ?? []
+				}).aliases, firstEntry.aliases ?? []);
+				if (aliases.length !== (firstEntry.aliases ?? []).length) writeAliases(first, firstEntry, aliases);
+				if (!await acknowledged(first, timeoutMs)) return "not-acknowledged";
+				if (others.filter((id, index) => graph.docSync(id).doc.getText("content").toString() !== texts[index + 1]).length > 0 || !oneName(docIds)) return "changed-after-append";
+				for (const id of others) {
+					creationClaims.delete(id);
+					await graph.deleteDoc(id);
+					registry.delete(id);
+				}
+				return "merged";
+			} finally {
+				materialised.release();
+			}
+		},
 		async reconcile() {},
 		async resolveConflict() {},
-		async createJournal(date, body = "") {
+		async createJournal(date, body = "", createOptions) {
 			const day = date.trim();
 			if (!isJournalConcept(day)) throw new Error(`"${date}" is not a calendar day.`);
+			await confirmBeforeCreate();
 			if (docIdFor(day)) throw new Error(`A document for "${day}" already exists`);
-			const docId = crypto.randomUUID();
-			registry.set(docId, {
+			const docId = await graph.journalDocId(day);
+			const engine = graph.docSync(docId);
+			await graph.whenReady(docId);
+			const connected = graph.isConnected();
+			const caughtUp = connected && await reachedWithin(graph.caughtUpDoc(docId), CREATE_CONFIRM_MS);
+			if (docIdFor(day)) throw new Error(`A document for "${day}" already exists`);
+			const entry = {
 				kind: "journal",
 				date: day
-			});
-			if (body !== "") {
-				const ytext = graph.docSync(docId).doc.getText("content");
-				ytext.doc.transact(() => ytext.insert(0, body));
-			}
+			};
+			registry.set(docId, entry);
+			engine.claimCreation();
+			if (!caughtUp) holdCreationClaim(docId, entry);
+			const ytext = engine.doc.getText("content");
+			if (!connected && ytext.length > 0) ytext.doc.transact(() => ytext.delete(0, ytext.length), STORE);
+			else if (connected && !caughtUp && ytext.length > 0) console.warn(`[sync] "${day}" was started before its document caught up; its earlier text is kept`);
+			const template = createOptions?.template ?? "";
+			if (template !== "" && body.startsWith(template)) {
+				await seedTemplate(docId, template);
+				const rest = body.slice(template.length);
+				if (rest !== "") ytext.doc.transact(() => ytext.insert(template.length, rest));
+			} else if (body !== "") ytext.doc.transact(() => ytext.insert(0, body));
 			return day;
 		},
 		async createPage(title, body = "") {
 			if (isJournalConcept(title)) throw new Error(dayIsNotAPageName(title));
 			if (docIdFor(title)) throw new Error(`A page for "${title}" already exists`);
+			await confirmBeforeCreate();
+			if (docIdFor(title)) throw new Error(`A page for "${title}" already exists`);
 			const docId = crypto.randomUUID();
 			registry.set(docId, {
 				kind: "page",
@@ -24791,6 +25064,7 @@ function createServerDocumentStore(graph, options) {
 		async deleteDocument(concept) {
 			const docId = docIdFor(concept);
 			if (!docId) return;
+			creationClaims.delete(docId);
 			await graph.deleteDoc(docId);
 			registry.delete(docId);
 		},
@@ -24800,10 +25074,90 @@ function createServerDocumentStore(graph, options) {
 			unobserveDocUpdates();
 			for (const stop of resurrectors.values()) stop();
 			resurrectors.clear();
+			for (const stop of stopClaimWatches) stop();
+			stopClaimWatches.clear();
 			await graph.flushAll();
 			graph.dispose();
 		}
 	};
+	/**
+	* Confirm before create (ADR 0157): while connected, wait (bounded) for the registry's current
+	* catch-up, so a name another device created moments ago is seen before a second document is
+	* made for it. A reconnect starts a new catch-up cycle a microtask after the socket opens,
+	* which the yield lets begin. Offline nothing can arrive, and the create goes ahead at once.
+	*/
+	async function confirmBeforeCreate() {
+		if (!graph.isConnected()) return;
+		await Promise.resolve();
+		await reachedWithin(graph.rootCaughtUp(), CREATE_CONFIRM_MS);
+	}
+	/**
+	* Seed a [[Journal Template]] as one Yjs update whose client id is derived from the document,
+	* its generation and the template's text (ADR 0157). Two devices that start the day with the
+	* same template produce the same struct, which the CRDT keeps once. The generation keeps a day
+	* started again after a delete from reusing the struct the deleted generation held. If the
+	* struct is already here and deleted (a device's cached copy of that generation), it adds
+	* nothing, and the template is inserted as an ordinary edit instead.
+	*/
+	async function seedTemplate(docId, template) {
+		const engine = graph.docSync(docId);
+		const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${docId}\n${engine.generation()}\n${template}`)));
+		const seed = new Y.Doc();
+		seed.clientID = new DataView(digest.buffer).getUint32(0);
+		seed.getText("content").insert(0, template);
+		Y.applyUpdate(engine.doc, Y.encodeStateAsUpdate(seed), STORE);
+		seed.destroy();
+		const ytext = engine.doc.getText("content");
+		if (!ytext.toString().startsWith(template)) ytext.doc.transact(() => ytext.insert(0, template), STORE);
+	}
+	/** Whether every one of `docIds` is still in the registry under one name. */
+	function oneName(docIds) {
+		const keys = /* @__PURE__ */ new Set();
+		for (const id of docIds) {
+			const entry = registry.get(id);
+			if (!entry) return false;
+			keys.add(conceptKey(conceptOf(entry)));
+		}
+		return keys.size === 1;
+	}
+	/**
+	* Send a document's pending edits and wait, bounded, until the relay has acknowledged every
+	* one of them: what a Merge waits for before it deletes anything. False when it has not.
+	*/
+	async function acknowledged(docId, timeoutMs) {
+		const engine = graph.docSync(docId);
+		await engine.flush();
+		const deadline = Date.now() + timeoutMs;
+		while (engine.unsentOperations() > 0) {
+			if (disposed || Date.now() >= deadline) return false;
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+		return true;
+	}
+	/**
+	* Keep a creation claim until the registry has caught up once with this device connected
+	* (`creationClaims`). Every concurrent set this device's entry could lose to is then here.
+	*/
+	function holdCreationClaim(docId, entry) {
+		creationClaims.set(docId, entry);
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			stop();
+			stopClaimWatches.delete(stop);
+			(async () => {
+				await Promise.resolve();
+				await graph.rootCaughtUp();
+				if (creationClaims.get(docId) === entry) creationClaims.delete(docId);
+			})().catch(() => {});
+		};
+		const stop = graph.onActivity((activity) => {
+			if (activity.connection === "open") release();
+		});
+		stopClaimWatches.add(stop);
+		if (graph.isConnected()) release();
+	}
 	async function confirmRegistry(timeoutMs = 5e3) {
 		if (registryConfirmed) return true;
 		if (!graph.isConnected()) return false;
@@ -25185,7 +25539,7 @@ async function openHeadlessGraph(deps) {
 						continue;
 					}
 					if (documentProtection(read.text).kind === "document") continue;
-					bodies.set(identity.concept, bodyOf(read.text).body);
+					bodies.set(identity.concept, bodyOf$1(read.text).body);
 				}
 				return {
 					bodies,