dsh-mnemon 0.5.28 → 0.5.29

package/lib/index.js

@@ -7,7 +7,7 @@ import z from "@deepseek-ai/schemastery";
 import { basename, delimiter, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { resolveEmbedding, resolvePersistenceStrategy, resolveRecallQuality } from "dsh-mnemon-source-memory-spaces";
 import { createHash, randomUUID } from "node:crypto";
-import { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { strToU8, unzipSync, zipSync } from "fflate";
 import { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_VERSION } from "dsh-mnemon-source-documents/contracts";
@@ -843,6 +843,315 @@ var MnemonMachineStore = class {
 	}
 };
 //#endregion
+//#region src/host/space-identity.ts
+/**
+* What a Memory Space holds, as opposed to how it was used, and the merge of two versions of one.
+*
+* Mnemon writes to a space whenever it is read: a recall, search or show raises
+* `access_count`, stamps `last_accessed_at` and logs the read in `oplog`. Two machines
+* that only read the same space therefore never hold the same `mnemon.db` bytes, and a
+* merge that compares bytes kept the other machine's space as a new one on every sync,
+* doubling the spaces each round (#370). Spaces are compared by their content instead:
+* every table, column and row, the edges included, except the usage columns, the read log
+* and the derived embedding and effective importance.
+*
+* Rows are compared by their columns in name order, so the order a table declares them in
+* does not matter. One version contains another when it holds every row of it. Two versions
+* of one space merge by adding to this machine's database the rows only the other holds:
+* this machine's rows, read counts, read log and schema stay as they are, and the result holds
+* the memories of both. A row both sides hold differently, a memory edited or forgotten on
+* one of them, refuses the merge, and the caller keeps a copy instead.
+*
+* It needs `node:sqlite` (Node 22.13, 23.4 and later). Without it, for bytes that are not a
+* readable database, for a database with a virtual table, or past the row limits, the identity
+* is the bytes' digest, which is what merges compared before, and such a space contains and
+* merges with no other: a copy is kept, never a memory lost.
+*/
+/** Written by reading a space: the read log. */
+const USAGE_TABLES = /* @__PURE__ */ new Set(["oplog"]);
+/** Written by reading a space, or derived from what it holds. */
+const USAGE_COLUMNS = /* @__PURE__ */ new Set([
+	"access_count",
+	"last_accessed_at",
+	"effective_importance",
+	"embedding"
+]);
+const SCRATCH_PREFIX = ".dsh-space-identity-";
+/**
+* Past this many rows a space is compared by its bytes, and past the second limit every space
+* a merge reads after it. A merge runs under the Pack lock, so a crafted database must not hold
+* the Host or the lock for long: 120,000 real rows read in about 0.4 s.
+*/
+const MEMORY_SPACE_IDENTITY_MAX_ROWS = 5e5;
+const MEMORY_SPACE_MERGE_MAX_ROWS = 2e6;
+function sqlite() {
+	try {
+		return process.getBuiltinModule?.("node:sqlite");
+	} catch {
+		return;
+	}
+}
+function quote(name) {
+	return "\"" + name.replaceAll("\"", "\"\"") + "\"";
+}
+/** A cell as JSON that keeps SQLite's types apart: 1, 1.0, '1', x'01' and NULL all differ. */
+function cell(value) {
+	if (value instanceof Uint8Array) return { blob: Buffer.from(value).toString("base64") };
+	if (typeof value === "bigint") return { integer: String(value) };
+	if (typeof value === "number") return { real: Object.is(value, -0) ? "-0" : String(value) };
+	return value;
+}
+/** 128 bits of a row's digest: enough to tell rows apart, half the memory of the whole digest. */
+function rowDigest(columns, row) {
+	return createHash("sha256").update(JSON.stringify(columns.map((column) => cell(row[column])))).digest("base64").slice(0, 22);
+}
+function digest(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+function sameBytes(left, right) {
+	return left === right || Buffer.from(left.buffer, left.byteOffset, left.byteLength).equals(right);
+}
+/** Cleanup never fails a merge: a copy another process holds open is swept by the next one. */
+function remove(path) {
+	try {
+		rmSync(path, {
+			recursive: true,
+			force: true,
+			maxRetries: 3
+		});
+	} catch {}
+}
+/**
+* Reads what each database holds once, and merges two of them. A merge holds one under the
+* Memory Spaces lock and disposes it at the end, so the copies a Host that stopped mid-merge
+* left behind are swept first.
+*/
+var MemorySpaceIdentity = class {
+	parent;
+	module;
+	maxRows;
+	scratch;
+	known = /* @__PURE__ */ new WeakMap();
+	projections = /* @__PURE__ */ new WeakMap();
+	remaining;
+	/** `parent` holds the short-lived copies a database is read from: the storage root. */
+	constructor(parent, module = sqlite, maxRows = MEMORY_SPACE_IDENTITY_MAX_ROWS, maxMergeRows = MEMORY_SPACE_MERGE_MAX_ROWS) {
+		this.parent = parent;
+		this.module = module;
+		this.maxRows = maxRows;
+		this.remaining = maxMergeRows;
+	}
+	of(bytes) {
+		return this.contents(bytes)?.identity ?? "bytes:" + digest(bytes);
+	}
+	/** Whether `outer` holds every row `inner` holds; `outer` may have columns `inner` lacks. */
+	contains(outer, inner) {
+		if (sameBytes(outer, inner)) return true;
+		const whole = this.contents(outer);
+		const part = this.contents(inner);
+		if (whole === void 0 || part === void 0) return false;
+		for (const [name, table] of part.tables) {
+			const present = this.rowsOn(outer, whole, name, table.columns);
+			if (present === void 0) return false;
+			for (const row of table.rows) if (!present.has(row)) return false;
+		}
+		return true;
+	}
+	/**
+	* `local` with the rows only `incoming` holds added to it, or undefined when the two cannot
+	* merge: a row both hold differently, a table or column `local` lacks, or a database that
+	* cannot be read. `local` itself comes back when it already holds everything.
+	*/
+	merge(local, incoming) {
+		if (sameBytes(local, incoming)) return local;
+		const mine = this.contents(local);
+		const theirs = this.contents(incoming);
+		if (mine === void 0 || theirs === void 0) return void 0;
+		const missing = /* @__PURE__ */ new Map();
+		for (const [name, table] of theirs.tables) {
+			const present = this.rowsOn(local, mine, name, table.columns);
+			if (present === void 0) return void 0;
+			const rows = new Set([...table.rows].filter((row) => !present.has(row)));
+			if (rows.size > 0) missing.set(name, rows);
+		}
+		if (missing.size === 0) return local;
+		const module = this.module();
+		const directory = this.directory();
+		if (module === void 0 || directory === void 0) return void 0;
+		const target = join(directory, randomUUID() + ".db");
+		const source = join(directory, randomUUID() + ".db");
+		let writer;
+		let reader;
+		try {
+			writeFileSync(target, local, { mode: 384 });
+			writeFileSync(source, incoming, { mode: 384 });
+			writer = this.open(module, target, false);
+			reader = this.open(module, source, true);
+			if (writer === void 0 || reader === void 0) return void 0;
+			writer.exec("BEGIN IMMEDIATE");
+			writer.exec("PRAGMA defer_foreign_keys = ON");
+			for (const [name, rows] of missing) {
+				const table = theirs.tables.get(name);
+				const own = mine.tables.get(name);
+				const written = table.all.filter((column) => own.all.includes(column));
+				const insert = writer.prepare(`INSERT INTO ${quote(name)} (${written.map(quote).join(", ")}) VALUES (${written.map(() => "?").join(", ")})`);
+				const statement = reader.prepare(`SELECT ${written.map(quote).join(", ")} FROM ${quote(name)}`);
+				statement.setReadBigInts(true);
+				for (const row of statement.iterate()) {
+					if (!this.spend()) throw new Error("the merge read limit was reached");
+					if (!rows.has(rowDigest(table.columns, row))) continue;
+					insert.run(...written.map((column) => row[column]));
+				}
+			}
+			writer.exec("COMMIT");
+			writer.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+			writer.close();
+			writer = void 0;
+			return readFileSync(target);
+		} catch {
+			return;
+		} finally {
+			for (const database of [writer, reader]) try {
+				database?.close();
+			} catch {}
+			for (const path of [target, source]) for (const suffix of [
+				"",
+				"-wal",
+				"-shm",
+				"-journal"
+			]) remove(path + suffix);
+		}
+	}
+	dispose() {
+		if (this.scratch !== void 0) remove(this.scratch);
+		this.scratch = void 0;
+	}
+	spend() {
+		this.remaining -= 1;
+		return this.remaining >= 0;
+	}
+	contents(bytes) {
+		const known = this.known.get(bytes);
+		if (known !== void 0) return known ?? void 0;
+		const contents = this.read(bytes);
+		this.known.set(bytes, contents ?? null);
+		return contents;
+	}
+	/** The digests of a table's rows over `columns`, which may leave out columns the table has. */
+	rowsOn(bytes, contents, name, columns) {
+		const table = contents.tables.get(name);
+		if (table === void 0 || !columns.every((column) => table.columns.includes(column))) return void 0;
+		if (columns.length === table.columns.length) return table.rows;
+		const key = JSON.stringify([name, columns]);
+		const cached = this.projections.get(bytes) ?? /* @__PURE__ */ new Map();
+		this.projections.set(bytes, cached);
+		if (!cached.has(key)) cached.set(key, this.withCopy(bytes, true, (database) => this.digests(database, name, columns) ?? null) ?? null);
+		return cached.get(key) ?? void 0;
+	}
+	digests(database, name, columns) {
+		const rows = /* @__PURE__ */ new Set();
+		if (columns.length === 0) return rows;
+		const statement = database.prepare(`SELECT ${columns.map(quote).join(", ")} FROM ${quote(name)}`);
+		statement.setReadBigInts(true);
+		let budget = this.maxRows;
+		for (const row of statement.iterate()) {
+			budget -= 1;
+			if (budget < 0 || !this.spend()) return void 0;
+			rows.add(rowDigest(columns, row));
+		}
+		return rows;
+	}
+	directory() {
+		try {
+			if (this.scratch === void 0) {
+				for (const name of readdirSync(this.parent)) if (name.startsWith(SCRATCH_PREFIX)) remove(join(this.parent, name));
+			}
+			if (this.scratch === void 0 || !existsSync(this.scratch)) this.scratch = mkdtempSync(join(this.parent, SCRATCH_PREFIX));
+		} catch {
+			return;
+		}
+		return this.scratch;
+	}
+	/** A connection to a private copy, refused when the copy is missing or empty rather than created. */
+	open(module, path, readOnly) {
+		if (!existsSync(path)) return void 0;
+		const database = new module.DatabaseSync(path, { readOnly });
+		database.exec("PRAGMA trusted_schema = OFF");
+		const pages = database.prepare("PRAGMA page_count").get();
+		if (Number(pages?.page_count ?? 0) <= 0) {
+			database.close();
+			return;
+		}
+		return database;
+	}
+	withCopy(bytes, readOnly, use) {
+		const module = this.module();
+		if (module === void 0) return void 0;
+		const directory = this.directory();
+		if (directory === void 0) return void 0;
+		const path = join(directory, randomUUID() + ".db");
+		let database;
+		try {
+			writeFileSync(path, bytes, { mode: 384 });
+			database = this.open(module, path, readOnly);
+			return database === void 0 ? void 0 : use(database);
+		} catch {
+			return;
+		} finally {
+			try {
+				database?.close();
+			} catch {}
+			for (const suffix of [
+				"",
+				"-wal",
+				"-shm",
+				"-journal"
+			]) remove(path + suffix);
+		}
+	}
+	read(bytes) {
+		return this.withCopy(bytes, true, (database) => {
+			const listed = database.prepare("SELECT name, type FROM pragma_table_list WHERE schema = 'main'").all();
+			if (listed.some((entry) => entry.type !== "table" && entry.type !== "view")) return void 0;
+			const names = listed.filter((entry) => entry.type === "table" && !entry.name.startsWith("sqlite_") && !USAGE_TABLES.has(entry.name)).map((entry) => entry.name).sort();
+			const hash = createHash("sha256");
+			const tables = /* @__PURE__ */ new Map();
+			let budget = this.maxRows;
+			for (const name of names) {
+				const all = database.prepare(`PRAGMA table_info(${quote(name)})`).all().map((column) => column.name);
+				const columns = all.filter((column) => !USAGE_COLUMNS.has(column)).sort();
+				const rows = [];
+				if (columns.length > 0) {
+					const statement = database.prepare(`SELECT ${columns.map(quote).join(", ")} FROM ${quote(name)}`);
+					statement.setReadBigInts(true);
+					for (const row of statement.iterate()) {
+						budget -= 1;
+						if (budget < 0 || !this.spend()) return void 0;
+						rows.push(rowDigest(columns, row));
+					}
+				}
+				rows.sort();
+				hash.update(JSON.stringify([
+					"table",
+					name,
+					columns,
+					rows.length
+				]));
+				for (const row of rows) hash.update(row);
+				tables.set(name, {
+					columns,
+					all,
+					rows: new Set(rows)
+				});
+			}
+			return {
+				identity: "content:" + hash.digest("hex"),
+				tables
+			};
+		});
+	}
+};
+//#endregion
 //#region src/host/pack.ts
 const MNEMON_PACK_FORMAT = "mnemonpack";
 const MNEMON_PACK_MIME = "application/zip";
@@ -970,9 +1279,19 @@ function parseEntryOrigin(value) {
 		at: origin.at
 	};
 }
+/**
+* Whole groups of four from the base64 alphabet, padded with at most two `=` at the end. The
+* length check and one character class keep this a flat loop at any size. A pattern that repeats
+* a four-character group keeps a backtracking entry per group, and V8 threw "Maximum call stack
+* size exceeded" once a payload passed about 4.5 MB (#368). The `u` flag stays off: under it,
+* V8 13 (Node 24) does the same for a class over a string holding a character above U+00FF.
+*/
+function isBase64(value) {
+	return value.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(value);
+}
 function decodeArchive(base64) {
 	if (typeof base64 !== "string" || base64 === "" || base64.length > Math.ceil(16777216) * 4 + 4) throw new Error("Mnemon Pack archive is empty or too large");
-	if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(base64)) throw new Error("Mnemon Pack payload is not valid base64");
+	if (!isBase64(base64)) throw new Error("Mnemon Pack payload is not valid base64");
 	const bytes = Buffer.from(base64, "base64");
 	if (bytes.length === 0 || bytes.length > 50331648) throw new Error("Mnemon Pack archive is empty or too large");
 	return bytes;
@@ -1630,24 +1949,86 @@ function mergeTombstoneFiles(current, incoming) {
 		tombstones: [...byKey.values()].sort((left, right) => left.deletedAt < right.deletedAt ? -1 : left.deletedAt > right.deletedAt ? 1 : 0)
 	};
 }
-function mergeDocuments(root, pack) {
+/**
+* One document's version as a sync agrees on it: every field but the time it was last read,
+* which a read moves without changing the document. A title, an archive or a link is as much
+* a part of it as the text.
+*/
+function documentVersion(document) {
+	const { lastAccessedAt: _read, ...fields } = document;
+	return sha256$1(canonicalJson(fields));
+}
+/** JSON with every object's keys in order and unset ones left out, so the same record always hashes the same. */
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const fields = value;
+		return `{${Object.keys(fields).filter((key) => fields[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(fields[key])}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+/** Whether two records say the same thing to a reader: the text, the title, the description and the archive. */
+function sameDocument(left, right) {
+	return left.contentHash === right.contentHash && left.title === right.title && left.description === right.description && left.status === right.status && (left.archiveSummary ?? "") === (right.archiveSummary ?? "");
+}
+/** Each document's version in one payload, by id, or nothing when the payload holds no valid Documents index. */
+function documentVersions(files) {
+	const bytes = files["payload/documents/index.json"];
+	if (bytes === void 0) return void 0;
+	try {
+		return Object.fromEntries(parseDocumentIndex(json$1(bytes, "payload/documents/index.json")).documents.map((document) => [document.id, documentVersion(document)]));
+	} catch {
+		return;
+	}
+}
+/**
+* `base` is each document's version as this machine and the branch last agreed on it, which
+* only a sync channel knows, and it decides only for a document both hold. One the branch did
+* not change since then keeps this machine's version, edited or not. One only the branch
+* changed is the newer version of the same document and replaces the one here, unless its
+* revision is lower than this machine's, as an older dsh-mnemon can publish; that one is kept
+* beside it, as a merge without `base` keeps every document whose text differs.
+*/
+function mergeDocuments(root, pack, base) {
 	const current = readCurrentDocuments(root);
 	const incoming = archiveDocuments(pack);
 	const ids = new Map(current.index.documents.map((document) => [document.id, document]));
+	const add = (document, bytes) => {
+		current.index.documents.push(document);
+		current.files.set(document.id, bytes);
+		ids.set(document.id, document);
+	};
+	const copy = (source) => {
+		const remapped = remapDocument(source, incoming.files.get(source.id), randomUUID());
+		add(remapped.document, remapped.bytes);
+	};
 	for (const source of incoming.index.documents) {
 		const existing = ids.get(source.id);
+		const agreed = existing !== void 0 && base !== void 0 && Object.hasOwn(base, source.id) ? base[source.id] : void 0;
+		if (existing !== void 0 && agreed !== void 0) {
+			if (documentVersion(source) === agreed) continue;
+			const at = current.index.documents.indexOf(existing);
+			if (documentVersion(existing) !== agreed) {
+				const kept = {
+					...existing,
+					revision: Math.max(existing.revision, source.revision) + 1
+				};
+				current.index.documents[at] = kept;
+				ids.set(source.id, kept);
+				if (!current.index.documents.some((document) => sameDocument(document, source))) copy(source);
+				continue;
+			}
+			if (source.revision >= existing.revision) {
+				current.index.documents[at] = source;
+				current.files.set(source.id, incoming.files.get(source.id));
+				ids.set(source.id, source);
+				continue;
+			}
+		}
 		if (existing !== void 0 && existing.contentHash === source.contentHash) continue;
 		if (existing !== void 0 && current.index.documents.some((document) => document.contentHash === source.contentHash)) continue;
-		let document = source;
-		let bytes = incoming.files.get(source.id);
-		if (existing !== void 0) {
-			const remapped = remapDocument(source, bytes, randomUUID());
-			document = remapped.document;
-			bytes = remapped.bytes;
-		}
-		current.index.documents.push(document);
-		current.files.set(document.id, bytes);
-		ids.set(document.id, document);
+		if (existing !== void 0) copy(source);
+		else add(source, incoming.files.get(source.id));
 	}
 	if (current.index.documents.filter((document) => document.status === "active").reduce((sum, document) => sum + document.sizeBytes, 0) > DOCUMENTS_ACTIVE_LIMIT_BYTES) throw new Error(`merged Documents exceed the ${DOCUMENTS_ACTIVE_LIMIT_BYTES} byte active limit`);
 	return current;
@@ -1656,26 +2037,43 @@ function mergeRegistry(root, pack) {
 	const current = readCurrentRegistry(root);
 	const incoming = archiveRegistry(pack);
 	const ids = new Set(current.registry.bodies.map((body) => body.id));
-	for (const source of incoming.registry.bodies) {
-		let body = source;
-		const sourceDb = incoming.databases.get(source.id);
-		if (ids.has(source.id)) {
-			const currentDb = current.databases.get(source.id);
-			const incomingHash = sha256$1(sourceDb);
-			if (sha256$1(currentDb) === incomingHash) continue;
-			if ([...current.databases.values()].some((database) => sha256$1(database) === incomingHash)) continue;
-			const id = randomUUID();
-			body = {
-				...source,
-				id,
-				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-			};
-		}
-		ids.add(body.id);
-		current.registry.bodies.push(body);
-		current.databases.set(body.id, sourceDb);
+	const identity = new MemorySpaceIdentity(root);
+	try {
+		const covers = (outer, inner) => identity.of(outer) === identity.of(inner) || identity.contains(outer, inner);
+		const held = (database, accept) => current.registry.bodies.some((body) => accept(body) && covers(current.databases.get(body.id), database));
+		const add = (body, database) => {
+			ids.add(body.id);
+			current.registry.bodies.push(body);
+			current.databases.set(body.id, database);
+		};
+		for (const source of incoming.registry.bodies) {
+			const sourceDb = incoming.databases.get(source.id);
+			if (ids.has(source.id)) {
+				const localDb = current.databases.get(source.id);
+				if (covers(localDb, sourceDb)) continue;
+				const merged = identity.merge(localDb, sourceDb);
+				if (merged !== void 0) {
+					current.databases.set(source.id, merged);
+					continue;
+				}
+				if (held(sourceDb, (body) => body.id !== source.id)) continue;
+				const copy = current.registry.bodies.find((body) => body.id !== source.id && body.name === source.name && identity.contains(sourceDb, current.databases.get(body.id)));
+				const advanced = copy === void 0 ? void 0 : identity.merge(current.databases.get(copy.id), sourceDb);
+				if (copy !== void 0 && advanced !== void 0) {
+					current.databases.set(copy.id, advanced);
+					continue;
+				}
+				add({
+					...source,
+					id: randomUUID(),
+					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}, sourceDb);
+			} else if (!held(sourceDb, (body) => body.name === source.name)) add(source, sourceDb);
+		}
+		return current;
+	} finally {
+		identity.dispose();
 	}
-	return current;
 }
 function persistedStore(root) {
 	try {
@@ -1730,7 +2128,7 @@ function stageImport(root, pack, components, mode, runtimeLimits, options = {})
 			keepRuntimeArchive(root, join(staging, "runtime"));
 		}
 		if (components.includes("documents")) {
-			const documents = mode === "merge" ? mergeDocuments(root, pack) : archiveDocuments(pack);
+			const documents = mode === "merge" ? mergeDocuments(root, pack, options.documentsBase) : archiveDocuments(pack);
 			writeDocuments(join(staging, "documents"), documents.index, documents.files);
 		}
 		if (components.includes("memory-spaces")) {
@@ -1967,6 +2365,10 @@ var MnemonPackManager = class {
 			occupied: Object.fromEntries(COMPONENT_ORDER.map((component) => [component, occupied(this.root, component)]))
 		};
 	}
+	/**
+	* `documentsBase` is each document's version, by id, as a sync channel last agreed on it with
+	* the branch; a merge uses it to tell an older version from a divergent one. A ZIP import has none.
+	*/
 	async importPack(base64, options) {
 		const pack = parseArchive(base64, this.runtimeLimits);
 		if (options.mode !== "merge" && options.mode !== "replace") throw new Error("Pack import mode must be merge or replace");
@@ -2562,6 +2964,17 @@ function headerRecord(headers) {
 	if (typeof headers.entries === "function") return Object.fromEntries(headers.entries());
 	return { ...headers };
 }
+/**
+* What a tunnelled request read back, as a `fetch` answer: the status, the text and its
+* content type, which is all this channel uses. The type says how to read a body that
+* is not JSON, such as the form GitHub's sign-in answers with when no JSON was asked for.
+*/
+function tunnelAnswer(status, type, text) {
+	return new Response(status === 204 || status === 205 || status === 304 ? null : text, {
+		status,
+		...type === void 0 ? {} : { headers: { "content-type": type } }
+	});
+}
 /** The request one tunnel performs, as a `fetch`-shaped answer. */
 function tunnelRequest(agent, url, init) {
 	return new Promise((resolve, reject) => {
@@ -2579,9 +2992,8 @@ function tunnelRequest(agent, url, init) {
 			});
 			response.once("error", reject);
 			response.once("end", () => {
-				const status = response.statusCode ?? 502;
-				const text = Buffer.concat(chunks).toString("utf8");
-				resolve(new Response(status === 204 || status === 205 || status === 304 ? null : text, { status }));
+				const type = response.headers["content-type"];
+				resolve(tunnelAnswer(response.statusCode ?? 502, type, Buffer.concat(chunks).toString("utf8")));
 			});
 		});
 		if (typeof init.body === "string") request.write(init.body);
@@ -2688,7 +3100,9 @@ var MnemonSyncError = class extends Error {
 * process-wide dispatcher, then one retry through a proxy discovered from the
 * environment or from this machine's own settings, so a network that reaches
 * GitHub only through a proxy still signs in. Failures report GitHub's error
-* code, the HTTP status and the transport reason only, never a response body.
+* code, the HTTP status and the transport reason, and a device code answer that
+* cannot be used adds its content type and field names; never a value from a
+* response body.
 */
 const MNEMON_GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code";
 const MNEMON_GITHUB_ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
@@ -2703,7 +3117,6 @@ const MNEMON_GITHUB_SCOPE = "repo";
 */
 const MNEMON_SYNC_GITHUB_CREDENTIAL_KEY = "dsh-mnemon/github";
 const MNEMON_GITHUB_REQUEST_TIMEOUT_MS = 3e4;
-const MNEMON_GITHUB_DEFAULT_INTERVAL_MS = 5e3;
 const MNEMON_GITHUB_SLOW_DOWN_MS = 5e3;
 const MNEMON_GITHUB_MAX_INTERVAL_MS = 6e4;
 const MNEMON_GITHUB_FLOW_LIMIT_MS = 36e5;
@@ -2721,6 +3134,23 @@ function codeOf(body) {
 	const fields = record$5(body);
 	return text$1(fields?.error) ?? text$1(fields?.message);
 }
+/** A positive count GitHub sends as a JSON number, or as a string in a form-encoded answer. */
+function count(value) {
+	const number = typeof value === "string" && /^\d{1,9}$/u.test(value) ? Number(value) : value;
+	return typeof number === "number" && Number.isFinite(number) && number > 0 ? number : void 0;
+}
+/** A key that reads as a field name; anything else in a body that only claimed to be a form could hold a value. */
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/u;
+/**
+* What an answer GitHub sent looked like, without any of its values: those can be a
+* device code or a token. Enough to tell a proxy's HTML page from a reply that lost a field.
+*/
+function shapeOf(answer) {
+	const keys = Object.keys(record$5(answer.body) ?? {});
+	const names = keys.filter((key) => FIELD_NAME.test(key)).slice(0, 8);
+	const listed = keys.length > names.length ? [...names, String(keys.length - names.length) + " other"] : names;
+	return "HTTP " + String(answer.status) + ", content-type " + (answer.type ?? "none") + ", fields: " + (listed.length === 0 ? "none" : listed.join(", "));
+}
 function failure$2(action, status, body) {
 	const code = codeOf(body);
 	const message = code === void 0 ? action + " failed with HTTP " + String(status) : action + " failed: " + code;
@@ -2867,16 +3297,16 @@ var MnemonGitHubAuth = class {
 		const deviceCode = text$1(fields?.device_code);
 		const userCode = text$1(fields?.user_code);
 		const verificationUri = text$1(fields?.verification_uri);
-		if (deviceCode === void 0 || userCode === void 0 || verificationUri === void 0) throw new Error("the GitHub device code answer was incomplete");
-		const expiresIn = typeof fields?.expires_in === "number" ? fields.expires_in : 900;
-		const interval = typeof fields?.interval === "number" ? fields.interval : MNEMON_GITHUB_DEFAULT_INTERVAL_MS / 1e3;
+		if (deviceCode === void 0 || userCode === void 0 || verificationUri === void 0) throw new Error("the GitHub device code answer was incomplete (" + shapeOf(answer) + ")");
+		const expiresIn = count(fields?.expires_in) ?? 900;
+		const intervalMs = Math.min(Math.max((count(fields?.interval) ?? 5) * 1e3, 1e3), MNEMON_GITHUB_MAX_INTERVAL_MS);
 		this.flow = {
 			deviceCode,
 			userCode,
 			verificationUri,
 			expiresAt: this.now() + Math.min(expiresIn * 1e3, MNEMON_GITHUB_FLOW_LIMIT_MS),
-			intervalMs: Math.max(interval * 1e3, 1e3),
-			nextPollAt: this.now() + Math.max(interval * 1e3, 1e3)
+			intervalMs,
+			nextPollAt: this.now() + intervalMs
 		};
 		return this.status();
 	}
@@ -3076,14 +3506,16 @@ var MnemonGitHubAuth = class {
 				signal
 			});
 			const raw = await response.text();
+			const type = response.headers.get("content-type") ?? void 0;
 			let body;
 			try {
 				body = raw === "" ? void 0 : JSON.parse(raw);
 			} catch {
-				body = void 0;
+				body = /^application\/x-www-form-urlencoded\b/iu.test(type ?? "") ? Object.fromEntries(new URLSearchParams(raw)) : void 0;
 			}
 			return {
 				status: response.status,
+				...type === void 0 ? {} : { type },
 				body
 			};
 		} finally {
@@ -3342,6 +3774,9 @@ const OWNERLESS_LOCK_MS = 9e5;
 /** The mirror's own Git config names the repository it was filled from. */
 const ORIGIN_KEY = "mnemon.origin";
 const LAST_RUN_FILE = "last-run.json";
+/** What this machine and the branch last agreed on: each document's version, by id, and the commit it was agreed at. */
+const BASE_FILE = "base.json";
+const AGREED_COMMIT = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u;
 const GIT_LABEL = "git";
 const MANIFEST = "manifest.json";
 const CHECKSUMS = "checksums.json";
@@ -3943,13 +4378,16 @@ var MnemonGitSync = class {
 		const remote = await this.readPrepared(settings, prepared);
 		let merged;
 		if (remote !== void 0) {
+			const base = await this.agreedDocuments(settings, remote.commit, signal);
 			const imported = await this.packs.importPack(Buffer.from(remote.archive).toString("base64"), {
 				mode: "merge",
 				tombstones: {
 					version: 1,
 					tombstones: remote.tombstones
-				}
+				},
+				...base === void 0 ? {} : { documentsBase: base }
 			});
+			if (imported.components.includes("documents")) this.agree(settings, remote.files, remote.commit);
 			merged = {
 				commit: remote.commit,
 				...remote.machine === void 0 ? {} : { machine: {
@@ -4018,6 +4456,7 @@ var MnemonGitSync = class {
 			pushed: false,
 			reason: prepared.tip === void 0 ? "nothing to publish" : "the branch already holds this payload"
 		};
+		if (published.pushed || !committed && prepared.tip !== void 0) this.agree(settings, entries, head);
 		const compaction = await this.compact(signal);
 		const summary = exported.manifest.summary.map((entry) => ({
 			...entry,
@@ -4089,6 +4528,70 @@ var MnemonGitSync = class {
 	lastRunPath() {
 		return join(this.store.directory(), "sync", LAST_RUN_FILE);
 	}
+	basePath() {
+		return join(this.store.directory(), "sync", BASE_FILE);
+	}
+	/** The repository, branch and directory one agreement belongs to. */
+	agreementScope(settings) {
+		return sha256Hex(new TextEncoder().encode(JSON.stringify([
+			settings.repoUrl,
+			settings.branch,
+			settings.subdir
+		])));
+	}
+	/**
+	* Each document's version as this machine and the branch last agreed on it, after the last
+	* merge or publish, when that still describes the branch at `tip`: the same repository,
+	* branch and directory, agreed at a commit `tip` descends from. A branch deleted and published
+	* again from another history has none, nor has the first sync, and a merge then keeps a copy
+	* of every document that differs, as before.
+	*/
+	async agreedDocuments(settings, tip, signal) {
+		let value;
+		try {
+			value = record$3(JSON.parse(readFileSync(this.basePath(), "utf8")));
+		} catch {
+			return;
+		}
+		if (value?.version !== 1 || value.scope !== this.agreementScope(settings)) return void 0;
+		const documents = record$3(value.documents);
+		if (typeof value.commit !== "string" || !AGREED_COMMIT.test(value.commit) || documents === void 0) return void 0;
+		if ((await this.git([
+			"merge-base",
+			"--is-ancestor",
+			value.commit,
+			tip
+		], {
+			cwd: this.store.mirror(),
+			signal
+		})).exitCode !== 0) return void 0;
+		return Object.fromEntries(Object.entries(documents).filter(([, version]) => typeof version === "string" && /^[a-f0-9]{64}$/u.test(version)));
+	}
+	/** Remember what this machine and the branch at `commit` now agree on. Bookkeeping never fails the run it follows. */
+	agree(settings, files, commit) {
+		const path = this.basePath();
+		const temporary = path + "." + String(process.pid) + ".tmp";
+		try {
+			const documents = documentVersions(files);
+			if (documents === void 0 || !AGREED_COMMIT.test(commit)) {
+				rmSync(path, { force: true });
+				return;
+			}
+			mkdirSync(join(path, ".."), {
+				recursive: true,
+				mode: 448
+			});
+			writeFileSync(temporary, JSON.stringify({
+				version: 1,
+				scope: this.agreementScope(settings),
+				commit,
+				documents
+			}, null, 2) + "\n", { mode: 384 });
+			renameSync(temporary, path);
+		} catch {
+			rmSync(temporary, { force: true });
+		}
+	}
 	/** Remember one finished run. Bookkeeping never fails the run it describes. */
 	recordRun(run) {
 		const path = this.lastRunPath();
@@ -4260,13 +4763,16 @@ var MnemonGitSync = class {
 		return this.lock(async () => {
 			const remote = await this.readRemote(settings, input.signal);
 			if (remote === void 0) throw this.absentPayload(settings);
+			const base = await this.agreedDocuments(settings, remote.commit, input.signal);
 			const imported = await this.packs.importPack(Buffer.from(remote.archive).toString("base64"), {
 				...options,
 				tombstones: {
 					version: 1,
 					tombstones: remote.tombstones
-				}
+				},
+				...base === void 0 ? {} : { documentsBase: base }
 			});
+			if (imported.components.includes("documents")) this.agree(settings, remote.files, remote.commit);
 			this.recordRun({
 				kind: "merge",
 				commit: remote.commit,
@@ -4551,8 +5057,7 @@ var MnemonGitSync = class {
 			});
 			if (renamed.exitCode !== 0) throw new Error("git symbolic-ref failed: " + tail(renamed.stderr || renamed.stdout));
 		}
-		const tip = await this.lsRemote(settings, credential, signal);
-		if (tip === void 0) {
+		if (await this.lsRemote(settings, credential, signal) === void 0) {
 			await this.startHistory(settings.branch, signal);
 			return {};
 		}
@@ -4579,7 +5084,7 @@ var MnemonGitSync = class {
 			signal
 		});
 		if (reset.exitCode !== 0) throw new Error("git reset failed: " + tail(reset.stderr || reset.stdout));
-		return { tip };
+		return { tip: await this.head(signal) };
 	}
 	/**
 	* Point the mirror at a branch the remote does not hold. The next commit starts a
@@ -5924,6 +6429,22 @@ function createRuntimeGraph(config, workspaceRoot, extensions) {
 		}
 	};
 }
+/**
+* When the Host asks a data directory's Providers again for namespaces they gained (#373): a
+* little after a runtime starts serving it, then, while a try cannot reach the Source, after
+* `retryDelayMs`, `attempts` tries in all. Tests shorten these.
+*/
+const PROVIDER_REDISCOVERY_TIMING = {
+	delayMs: 1e4,
+	retryDelayMs: 3e4,
+	attempts: 3
+};
+/** Data directories whose Provider namespaces this process has asked for again, or is asking now. */
+const rediscoveredDirectories = /* @__PURE__ */ new Set();
+/** An answer asking again cannot change: no Memory Spaces Source, or one older than this request. */
+function finalRediscoveryAnswer(error) {
+	return /unsupported Memory Spaces management mutation operation|is not installed/u.test(error instanceof Error ? error.message : String(error));
+}
 /** Resolve every property access against one generation, binding methods to it. */
 function liveProxy(resolve) {
 	return new Proxy({}, {
@@ -5962,6 +6483,8 @@ var LiveMnemonRuntime = class {
 	workspaceGraphs = /* @__PURE__ */ new Map();
 	agentGraphs = /* @__PURE__ */ new Map();
 	retiredGraphs = /* @__PURE__ */ new Set();
+	/** The start-up rediscovery each graph has waiting or running, to stop when the graph goes. */
+	rediscoveries = /* @__PURE__ */ new Map();
 	githubAuth;
 	autoBackupView;
 	closed = false;
@@ -5980,6 +6503,7 @@ var LiveMnemonRuntime = class {
 		this.packs = liveProxy(() => this.current.packs);
 		this.sync = liveProxy(() => this.current.sync);
 		this.reviews = liveProxy(() => this.current.reviews);
+		this.rediscoverProviders(initial);
 	}
 	/**
 	* Share one GitHub sign-in with every generation this runtime builds. The
@@ -6014,6 +6538,7 @@ var LiveMnemonRuntime = class {
 		this.current = next;
 		this.applyGitHubAuth(next);
 		this.applyAutoBackup(next);
+		this.rediscoverProviders(next);
 		this.retireGraph(previous);
 		for (const graph of this.workspaceGraphs.values()) this.retireGraph(graph);
 		this.workspaceGraphs.clear();
@@ -6051,6 +6576,8 @@ var LiveMnemonRuntime = class {
 		this.agentGraphs.clear();
 		this.workspaceGraphs.clear();
 		this.retiredGraphs.clear();
+		for (const stop of this.rediscoveries.values()) stop();
+		this.rediscoveries.clear();
 		for (const graph of graphs) graph.dispose();
 	}
 	/** Resolve the runtime that must serve one Agent execution. */
@@ -6099,11 +6626,64 @@ var LiveMnemonRuntime = class {
 			graph = createRuntimeGraph(this.current.config, key, this.extensions);
 			this.applyGitHubAuth(graph);
 			this.applyAutoBackup(graph);
+			this.rediscoverProviders(graph);
 			this.workspaceGraphs.set(key, graph);
 		}
 		return graph;
 	}
+	/**
+	* Ask the Providers of one data directory again for namespaces they gained, once per process,
+	* a little after a runtime this Host serves starts (#373); a graph built only to validate
+	* settings never asks. A read-only runtime asks nothing, and neither does one whose Memory
+	* Spaces layer is off or does not maintain itself automatically. A try that cannot reach the
+	* Source, before a generation serves for example, is made again a little later; one cut short
+	* because its runtime was replaced is left to the runtime that replaced it.
+	*/
+	rediscoverProviders(graph) {
+		if (!graph.config.writeEnabled || !allowsParticipation(graph.config, "memory-spaces", "maintain", "automatic")) return;
+		const directory = resolve(graph.directory);
+		const controller = new AbortController();
+		let timer;
+		let running = false;
+		const release = () => {
+			if (this.rediscoveries.get(graph) === stop) this.rediscoveries.delete(graph);
+		};
+		const schedule = (attempt, delayMs) => {
+			timer = setTimeout(() => void ask(attempt), delayMs);
+			timer.unref?.();
+		};
+		const ask = async (attempt) => {
+			timer = void 0;
+			if (rediscoveredDirectories.has(directory)) return release();
+			rediscoveredDirectories.add(directory);
+			running = true;
+			let again = false;
+			try {
+				await graph.source("memory-spaces").mutate("provider-rediscover", { trigger: "startup" }, controller.signal);
+			} catch (error) {
+				again = !finalRediscoveryAnswer(error);
+			} finally {
+				running = false;
+			}
+			if (controller.signal.aborted) return;
+			if (again) {
+				rediscoveredDirectories.delete(directory);
+				if (attempt < PROVIDER_REDISCOVERY_TIMING.attempts) return schedule(attempt + 1, PROVIDER_REDISCOVERY_TIMING.retryDelayMs);
+			}
+			release();
+		};
+		const stop = () => {
+			if (timer !== void 0) clearTimeout(timer);
+			if (running) rediscoveredDirectories.delete(directory);
+			controller.abort(/* @__PURE__ */ new Error("the Mnemon runtime was replaced"));
+		};
+		this.rediscoveries.get(graph)?.();
+		this.rediscoveries.set(graph, stop);
+		schedule(1, PROVIDER_REDISCOVERY_TIMING.delayMs);
+	}
 	retireGraph(graph) {
+		this.rediscoveries.get(graph)?.();
+		this.rediscoveries.delete(graph);
 		graph.retire();
 		if ([...this.agentGraphs.values()].some((binding) => binding.graph === graph)) this.retiredGraphs.add(graph);
 		else graph.dispose();