@evegoodevening/dsh-llmwiki 0.0.0-stage → 0.0.2

package/lib/index.js

@@ -0,0 +1,3281 @@
+import z from "@deepseek-ai/schemastery";
+import { createHash, randomBytes } from "node:crypto";
+import { extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, opendir, rename, rmdir, unlink } from "node:fs/promises";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/errors.ts
+const LLMWIKI_ERROR_CODES = [
+	"NOT_INITIALIZED",
+	"INVALID_PATH",
+	"SOURCE_NOT_FOUND",
+	"PAGE_NOT_FOUND",
+	"INVALID_PAGE",
+	"INVALID_PRECONDITION",
+	"PAGE_CONFLICT",
+	"LIMIT_EXCEEDED",
+	"ABORTED",
+	"UNSAFE_FILESYSTEM",
+	"INDEX_CORRUPT",
+	"INVALID_CURSOR",
+	"CATALOG_CORRUPT"
+];
+var LlmWikiError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "LlmWikiError";
+		this.code = code;
+	}
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
+};
+function isLlmWikiError(value) {
+	return value instanceof LlmWikiError;
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted === true) throw new LlmWikiError("ABORTED", "The operation was aborted.");
+}
+function invalidPath(message, options) {
+	return new LlmWikiError("INVALID_PATH", message, options);
+}
+function unsafeFilesystem(message, options) {
+	return new LlmWikiError("UNSAFE_FILESYSTEM", message, options);
+}
+//#endregion
+//#region src/command.ts
+const USAGE = "Usage: /wiki [status|lint|reindex]";
+function parseSubcommand(rawInput) {
+	const input = rawInput.trim();
+	if (input === "") return "status";
+	if (input === "status" || input === "lint" || input === "reindex") return input;
+}
+function formatIndex(index) {
+	if (!index.present) return "missing";
+	const version = index.formatVersion === null ? "unknown" : String(index.formatVersion);
+	return `${index.fresh ? "fresh" : "stale"} (version ${version}, ${index.sectionCount} sections)`;
+}
+function formatStatus(status) {
+	return [
+		"Wiki status",
+		`Initialized: ${status.initialized ? "yes" : "no"}`,
+		`Sources: ${status.sourceCount}`,
+		`Pages: ${status.pageCount}`,
+		`Index: ${formatIndex(status.index)}`
+	].join("\n");
+}
+function formatDiagnostic(diagnostic) {
+	const location = diagnostic.line === void 0 ? diagnostic.path : `${diagnostic.path}:${diagnostic.line}`;
+	return `- ${diagnostic.severity.toUpperCase()} ${diagnostic.code} ${location}: ${diagnostic.message}`;
+}
+function formatLint(report, limit) {
+	const displayed = report.diagnostics.slice(0, limit);
+	const omitted = report.diagnostics.length - displayed.length;
+	const lines = [`Wiki lint: ${report.errorCount} errors, ${report.warningCount} warnings across ${report.filesExamined} files.`, ...displayed.map(formatDiagnostic)];
+	if (omitted > 0) lines.push(`... ${omitted} more diagnostics omitted.`);
+	return lines.join("\n");
+}
+function formatReindex(receipt) {
+	return `Wiki reindexed: ${receipt.pageCount} pages, ${receipt.sectionCount} sections, index version ${receipt.formatVersion}.`;
+}
+function domainError(error) {
+	if (!isLlmWikiError(error)) throw error;
+	return {
+		kind: "error",
+		text: `${error.code}: ${error.message}`
+	};
+}
+function registerLlmWikiCommand(ctx, config) {
+	const service = ctx.llmwiki;
+	ctx.commands.register({
+		name: "wiki",
+		description: "Inspect, lint, or reindex the local wiki",
+		input: { hint: "[status|lint|reindex]" },
+		handler: async (invocation) => {
+			const subcommand = parseSubcommand(invocation.rawInput);
+			if (subcommand === void 0) return {
+				kind: "error",
+				text: USAGE
+			};
+			try {
+				if (subcommand === "status") return {
+					kind: "success",
+					text: formatStatus(await service.status(invocation.signal))
+				};
+				if (subcommand === "lint") return {
+					kind: "success",
+					text: formatLint(await service.lint(invocation.signal), config.commandDiagnosticLimit)
+				};
+				return {
+					kind: "success",
+					text: formatReindex(await service.reindex(invocation.signal))
+				};
+			} catch (error) {
+				return domainError(error);
+			}
+		}
+	});
+}
+//#endregion
+//#region src/config.ts
+const configSchema = z.object({
+	root: z.string().min(1).default(".llmwiki"),
+	maxSourceBytes: z.number().step(1).min(1).default(2 * 1024 * 1024),
+	maxPageBytes: z.number().step(1).min(1).default(512 * 1024),
+	maxResults: z.number().step(1).min(1).max(100).default(20),
+	maxSnippetBytes: z.number().step(1).min(64).max(16384).default(1200),
+	commandDiagnosticLimit: z.number().step(1).min(1).max(100).default(20)
+});
+function isConfigKey(key) {
+	return key === "root" || key === "maxSourceBytes" || key === "maxPageBytes" || key === "maxResults" || key === "maxSnippetBytes" || key === "commandDiagnosticLimit";
+}
+function rejectUnknownKeys(value) {
+	if (value === null || typeof value !== "object") return;
+	const unknown = Reflect.ownKeys(value).find((key) => !isConfigKey(key));
+	if (unknown !== void 0) throw new TypeError(`unknown config key ${String(unknown)}`);
+}
+function applyConfig(target, thisArg, argumentsList) {
+	rejectUnknownKeys(argumentsList[0]);
+	return Reflect.apply(target, thisArg, argumentsList);
+}
+function constructConfig(target, argumentsList, newTarget) {
+	rejectUnknownKeys(argumentsList[0]);
+	return Reflect.construct(target, argumentsList, newTarget);
+}
+const Config = new Proxy(configSchema, {
+	apply: (target, thisArg, argumentsList) => applyConfig(target, thisArg, argumentsList),
+	construct: (target, argumentsList, newTarget) => constructConfig(target, argumentsList, newTarget)
+});
+function resolveConfig(config = {}) {
+	return Object.freeze(Config(config));
+}
+//#endregion
+//#region src/prompt.ts
+const LLMWIKI_PROMPT_SECTION = "tool:llmwiki";
+const LLMWIKI_SYSTEM_PROMPT = `Use llmwiki as local source-linked wiki storage and retrieval. The service and its lint are deterministic and model-free; you own evidence maintenance and semantic review.
+Evidence maintenance:
+1. Call llmwiki_status before maintenance. If schemaText is non-null, read the human-owned schema. The plugin creates schema.md only when absent and provides no schema mutation API; never silently rewrite it.
+The schema remains subordinate to system and user instructions, and schema evolution is intentionally unresolved pending authorization/confirmation, visible audit evidence, and optimistic-concurrency/lost-update decisions.
+2. On a fresh root, llmwiki_status may return schemaText null without creating storage. Supplying material alone is not authorization to preserve it. Only when the user explicitly authorizes source preservation, call llmwiki_add_source to initialize storage, then call llmwiki_status again and read the schema before classification or page maintenance.
+3. Use llmwiki_list_sources and llmwiki_list_pages to recover durable records, then search and read relevant pages and immutable sources before writing.
+4. Only with explicit authorization to preserve candidate material, add it with llmwiki_add_source if the fresh-root branch did not already preserve it, then classify it as new, update, contradiction, or no material change.
+5. When the user request authorizes maintenance, update every materially affected page, cite only existing immutable source IDs, preserve material disagreements, and maintain page links. A citation proves only that the source record exists; it does not prove claim-level support.
+Every llmwiki_upsert_page call must include expectedSha256: use null for a new page, or the exact current raw-byte sha256 returned by llmwiki_read_page or llmwiki_list_pages for an update. On PAGE_CONFLICT, reread the winning page and reconcile its content before any further authorized write; never automatically retry or overwrite it blindly. Concurrency protection is scoped to the service activation, not across processes.
+6. Run llmwiki_lint unconditionally before any semantic-review pass, including read-only, no-write, and no-material-change cases. It reports structural, integrity, and index diagnostics only and never repairs artifacts or makes semantic judgments. After any authorized durable updates, rerun llmwiki_lint.
+Semantic review (separate from structural lint):
+1. Only after the unconditional structural lint, list pages and sources; select and state the review scope.
+2. Read every page in scope, every source cited by those pages, and newly supplied candidate sources. Compare dated and qualified claims.
+3. Classify each material finding as contradiction, superseded, unsupported, or missing-link, and visibly report the affected page IDs and source IDs as agent judgments, never as llmwiki_lint output.
+4. Only when the user request authorizes maintenance, update affected pages while preserving both sides of a disagreement or recording a clearly dated supersession, then maintain links and rerun structural lint.`;
+function registerLlmWikiPrompt(ctx) {
+	ctx.systemPrompt.section({
+		name: LLMWIKI_PROMPT_SECTION,
+		order: 116,
+		text: LLMWIKI_SYSTEM_PROMPT
+	});
+}
+//#endregion
+//#region src/paths.ts
+/** Keep shared descriptors alive until every started sibling settles, preserving the first failure. */
+async function allSettledOnFailure(values) {
+	try {
+		return await Promise.all(values);
+	} catch (cause) {
+		await Promise.allSettled(values);
+		throw cause;
+	}
+}
+/** Diagnostic metadata only; never authorizes a retry or pathname access. */
+var WikiTraversalError = class extends LlmWikiError {
+	segments;
+	entryKind;
+	constructor(segments, entryKind, cause) {
+		super("UNSAFE_FILESYSTEM", "Unable to open wiki directory safely.", { cause });
+		this.segments = segments;
+		this.entryKind = entryKind;
+	}
+};
+const code = (cause) => cause.code;
+function validateComponent(name) {
+	if (!name || name === "." || name === ".." || /[\\/\0]/u.test(name)) throw unsafeFilesystem("Invalid wiki path component.");
+}
+function sameIdentity(a, b) {
+	return a.dev === b.dev && a.ino === b.ino;
+}
+function sameFileSnapshot(a, b) {
+	return sameIdentity(a, b) && a.mode === b.mode && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+}
+function directoryFlags() {
+	if (process.platform !== "linux" || !constants.O_DIRECTORY || !constants.O_NOFOLLOW || !constants.O_NONBLOCK) throw unsafeFilesystem("Descriptor-contained filesystem access requires Linux with usable procfs.");
+	return constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+}
+async function closeScope(handle, action, publication) {
+	let failed = false;
+	try {
+		return await action();
+	} catch (cause) {
+		failed = true;
+		throw cause;
+	} finally {
+		try {
+			await handle.close();
+		} catch (cause) {
+			if (!failed && !publication?.committed) throw unsafeFilesystem("Unable to close wiki descriptor.", { cause });
+		}
+	}
+}
+async function checked(signal, action) {
+	throwIfAborted(signal);
+	try {
+		const value = await action();
+		throwIfAborted(signal);
+		return value;
+	} catch (cause) {
+		throwIfAborted(signal);
+		throw cause;
+	}
+}
+var WikiDirectory = class WikiDirectory {
+	handle;
+	segments;
+	operationRoot;
+	publication;
+	constructor(handle, segments, operationRoot, publication = { committed: false }) {
+		this.handle = handle;
+		this.segments = segments;
+		this.operationRoot = operationRoot;
+		this.publication = publication;
+	}
+	/** Internal commit boundary used by the atomic adapter, including ancestor cleanup. */
+	markCommitted() {
+		this.publication.committed = true;
+	}
+	/** Internal filesystem adapter seam. Only atomic.ts may use descriptor aliases. */
+	async withHandle(callback) {
+		return callback(this.handle, `/proc/self/fd/${this.handle.fd}`);
+	}
+	child(name) {
+		validateComponent(name);
+		return `/proc/self/fd/${this.handle.fd}/${name}`;
+	}
+	async identity() {
+		return this.handle.stat({ bigint: true });
+	}
+	async inspect(name, signal) {
+		try {
+			return await checked(signal, () => lstat(this.child(name), { bigint: true }));
+		} catch (cause) {
+			throwIfAborted(signal);
+			if (code(cause) === "ENOENT") return null;
+			throw unsafeFilesystem("Unable to inspect wiki entry.", { cause });
+		}
+	}
+	async directory(segments, options, callback) {
+		segments.forEach(validateComponent);
+		throwIfAborted(options.signal);
+		if (!segments.length) return callback(this);
+		const name = segments[0];
+		let handle;
+		try {
+			try {
+				handle = await open(this.child(name), directoryFlags());
+			} catch (cause) {
+				if (code(cause) !== "ENOENT" || !options.create) throw cause;
+				await checked(options.signal, async () => {
+					try {
+						await mkdir(this.child(name));
+					} catch (error) {
+						if (code(error) !== "EEXIST") throw unsafeFilesystem("The wiki filesystem operation failed.", { cause: error });
+					}
+				});
+				handle = await open(this.child(name), directoryFlags());
+			}
+		} catch (cause) {
+			throwIfAborted(options.signal);
+			if (cause instanceof LlmWikiError) throw cause;
+			if (code(cause) === "ENOENT" && !options.create) return null;
+			let entryKind = "unknown";
+			if (code(cause) === "ELOOP" || code(cause) === "ENOTDIR") {
+				const entry = await this.inspect(name, options.signal);
+				if (entry?.isSymbolicLink()) entryKind = "symlink";
+				else if (entry && !entry.isDirectory()) entryKind = "not-directory";
+			}
+			throw new WikiTraversalError([...this.segments, name], entryKind, cause);
+		}
+		return closeScope(handle, async () => {
+			throwIfAborted(options.signal);
+			if (!(await checked(options.signal, () => handle.stat({ bigint: true }))).isDirectory()) throw unsafeFilesystem("Wiki parent is not a directory.");
+			return new WikiDirectory(handle, [...this.segments, name], this.operationRoot ?? this, this.publication).directory(segments.slice(1), options, callback);
+		}, this.publication);
+	}
+	async read(name, signal) {
+		let handle;
+		try {
+			throwIfAborted(signal);
+			handle = await open(this.child(name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		} catch (cause) {
+			throwIfAborted(signal);
+			if (code(cause) === "ENOENT") return null;
+			throw unsafeFilesystem("Unable to open wiki file safely.", { cause });
+		}
+		return closeScope(handle, async () => {
+			throwIfAborted(signal);
+			const before = await checked(signal, () => handle.stat({ bigint: true }));
+			if (!before.isFile()) throw unsafeFilesystem("Wiki entry is not a regular file.");
+			const bytes = await checked(signal, () => handle.readFile());
+			const after = await checked(signal, () => handle.stat({ bigint: true }));
+			const entry = await this.inspect(name, signal);
+			if (!entry || !entry.isFile() || !sameFileSnapshot(before, after) || !sameFileSnapshot(before, entry)) throw unsafeFilesystem("Wiki file changed while reading.");
+			return {
+				bytes,
+				snapshot: {
+					name,
+					segments: [...this.segments, name],
+					stat: before
+				}
+			};
+		});
+	}
+	async list(signal) {
+		throwIfAborted(signal);
+		let dir;
+		try {
+			dir = await opendir(`/proc/self/fd/${this.handle.fd}`);
+		} catch (cause) {
+			throw unsafeFilesystem("Unable to enumerate pinned wiki directory.", { cause });
+		}
+		const entries = [];
+		let failed = false;
+		try {
+			while (true) {
+				const entry = await checked(signal, () => dir.read());
+				if (!entry) break;
+				const stat = await this.inspect(entry.name, signal);
+				if (!stat) throw unsafeFilesystem("Wiki entry disappeared during enumeration.");
+				entries.push({
+					name: entry.name,
+					segments: [...this.segments, entry.name],
+					stat
+				});
+			}
+		} catch (cause) {
+			failed = true;
+			throw cause;
+		} finally {
+			try {
+				await dir.close();
+			} catch (cause) {
+				if (!failed) throw unsafeFilesystem("Unable to close directory enumeration.", { cause });
+			}
+		}
+		return entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+	}
+	async validate(snapshot, signal) {
+		return await (this.operationRoot ?? this).directory(snapshot.segments.slice(0, -1), { signal }, async (parent) => {
+			const current = await parent.inspect(snapshot.name, signal);
+			return current !== null && sameFileSnapshot(snapshot.stat, current);
+		}) === true;
+	}
+	async createDirectory(name, signal) {
+		const existing = await this.directory([name], { signal }, (directory) => directory.identity());
+		if (existing) return {
+			created: false,
+			identity: existing
+		};
+		let created = true;
+		await checked(signal, async () => {
+			try {
+				await mkdir(this.child(name));
+			} catch (cause) {
+				if (code(cause) !== "EEXIST") throw unsafeFilesystem("The wiki filesystem operation failed.", { cause });
+				created = false;
+			}
+		});
+		const identity = await this.directory([name], { signal }, (directory) => directory.identity());
+		if (!identity) throw unsafeFilesystem("Created wiki directory disappeared.");
+		return {
+			created,
+			identity
+		};
+	}
+	async createFileExclusive(name, bytes, options = {}) {
+		throwIfAborted(options.signal);
+		let handle;
+		try {
+			handle = await open(this.child(name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, options.mode ?? 384);
+		} catch (cause) {
+			throwIfAborted(options.signal);
+			if (code(cause) === "EEXIST") {
+				if (!await this.read(name, options.signal)) throw unsafeFilesystem("Existing schema disappeared during initialization.");
+			}
+			throw cause;
+		}
+		let identity;
+		try {
+			await closeScope(handle, async () => {
+				identity = await handle.stat({ bigint: true });
+				throwIfAborted(options.signal);
+				await checked(options.signal, () => handle.writeFile(bytes));
+				await checked(options.signal, () => syncFile(handle));
+			});
+		} catch (cause) {
+			if (identity) try {
+				await this.unlink(name, identity);
+			} catch {}
+			throw cause;
+		}
+	}
+	atomicWrite(name, bytes, options = {}) {
+		return atomicWriteFile(this, name, bytes, options);
+	}
+	async unlink(name, expectedIdentity) {
+		if (expectedIdentity) {
+			const stat = await this.inspect(name);
+			if (!stat || !sameIdentity(stat, expectedIdentity)) return;
+		}
+		await unlink(this.child(name));
+	}
+	async removeCreatedSource(name, expectedIdentity, ownedNames) {
+		await this.directory([name], {}, async (directory) => {
+			if (!sameIdentity(await directory.identity(), expectedIdentity)) return;
+			for (const child of ownedNames) try {
+				await directory.unlink(child);
+			} catch {}
+		});
+		const stat = await this.inspect(name);
+		if (stat?.isDirectory() && sameIdentity(stat, expectedIdentity)) await rmdir(this.child(name));
+	}
+};
+async function withWikiRoot(authority, options, callback) {
+	const flags = directoryFlags();
+	throwIfAborted(options.signal);
+	let handle;
+	try {
+		handle = await open("/", flags);
+	} catch (cause) {
+		throw unsafeFilesystem("Unable to acquire filesystem authority.", { cause });
+	}
+	const publication = { committed: false };
+	let failed = false;
+	try {
+		throwIfAborted(options.signal);
+		const aliasStat = await lstat(`/proc/self/fd/${handle.fd}/.`, { bigint: true }).catch((cause) => {
+			throw unsafeFilesystem("Usable Linux procfs is required.", { cause });
+		});
+		const stat = await checked(options.signal, () => handle.stat({ bigint: true }));
+		if (!stat.isDirectory() || !sameIdentity(stat, aliasStat)) throw unsafeFilesystem("Descriptor alias capability is unavailable.");
+		await (await opendir(`/proc/self/fd/${handle.fd}`).catch((cause) => {
+			throw unsafeFilesystem("Descriptor enumeration capability is unavailable.", { cause });
+		})).close();
+		throwIfAborted(options.signal);
+		const segments = resolve(authority.root).split(sep).filter(Boolean);
+		for (let index = 0; index < segments.length; index += 1) {
+			const name = segments[index];
+			validateComponent(name);
+			const parent = new WikiDirectory(handle, segments.slice(0, index));
+			let next;
+			try {
+				try {
+					next = await open(`/proc/self/fd/${handle.fd}/${name}`, flags);
+				} catch (cause) {
+					if (code(cause) !== "ENOENT" || !options.create || authority.identity) throw cause;
+					await checked(options.signal, async () => {
+						try {
+							await mkdir(`/proc/self/fd/${handle.fd}/${name}`);
+						} catch (error) {
+							if (code(error) !== "EEXIST") throw unsafeFilesystem("Unable to create the configured wiki root.", { cause: error });
+						}
+					});
+					next = await open(`/proc/self/fd/${handle.fd}/${name}`, flags);
+				}
+			} catch (cause) {
+				throwIfAborted(options.signal);
+				if (cause instanceof LlmWikiError) throw cause;
+				if (code(cause) === "ENOENT") {
+					if (authority.identity) throw unsafeFilesystem("Initialized wiki root is missing.", { cause });
+					if (!options.create) return null;
+				}
+				let entryKind = "unknown";
+				if (code(cause) === "ELOOP" || code(cause) === "ENOTDIR") {
+					const entry = await parent.inspect(name, options.signal);
+					if (entry?.isSymbolicLink()) entryKind = "symlink";
+					else if (entry && !entry.isDirectory()) entryKind = "not-directory";
+				}
+				throw new WikiTraversalError(segments.slice(0, index + 1), entryKind, cause);
+			}
+			const previous = handle;
+			handle = next;
+			await previous.close();
+			throwIfAborted(options.signal);
+			if (!(await checked(options.signal, () => handle.stat({ bigint: true }))).isDirectory()) throw unsafeFilesystem("Wiki root component is not a directory.");
+		}
+		const root = new WikiDirectory(handle, [], void 0, publication);
+		if (authority.identity && !sameIdentity(authority.identity, await root.identity())) throw unsafeFilesystem("Initialized wiki root was replaced.");
+		throwIfAborted(options.signal);
+		return await callback(root);
+	} catch (cause) {
+		failed = true;
+		throw cause;
+	} finally {
+		try {
+			await handle.close();
+		} catch (cause) {
+			if (!failed && !publication.committed) throw unsafeFilesystem("Unable to close wiki descriptor.", { cause });
+		}
+	}
+}
+function wikiRelativeSegments(paths, target) {
+	const value = relative(paths.root, resolve(target));
+	if (value === ".." || value.startsWith(`..${sep}`) || isAbsolute(value)) throw unsafeFilesystem("Derived path escapes the wiki root.");
+	const segments = value ? value.split(sep) : [];
+	segments.forEach(validateComponent);
+	return segments;
+}
+function createWikiPaths(root, authority) {
+	if (!isAbsolute(root) || root.includes("\0")) throw new LlmWikiError("INVALID_PATH", "Wiki root must be an absolute filesystem path.");
+	root = resolve(root);
+	const sources = join(root, "sources"), pages = join(root, "pages"), index = join(root, ".index");
+	const derive = (target) => {
+		const value = relative(root, target);
+		if (!value || value === ".." || value.startsWith(`..${sep}`) || isAbsolute(value) || target.includes("\0")) throw unsafeFilesystem("Derived path escapes the wiki root.");
+		return target;
+	};
+	return Object.freeze({
+		root,
+		authority: authority ?? { root },
+		sources,
+		pages,
+		index,
+		schema: join(root, "schema.md"),
+		sourceDirectory: (id) => derive(join(sources, id)),
+		sourceContent: (id) => derive(join(sources, id, "content")),
+		sourceMetadata: (id) => derive(join(sources, id, "metadata.json")),
+		page: (id) => derive(join(pages, `${id}.md`)),
+		indexFile: (name) => derive(join(index, name))
+	});
+}
+//#endregion
+//#region src/atomic.ts
+const IGNORED_SYNC_ERROR_CODE = {
+	EINVAL: true,
+	ENOTSUP: true,
+	EOPNOTSUPP: true,
+	EBADF: true,
+	EPERM: true
+};
+async function syncFile(handle) {
+	try {
+		await handle.sync();
+	} catch (cause) {
+		if (IGNORED_SYNC_ERROR_CODE[cause.code ?? ""] !== true) throw cause;
+	}
+}
+const ATOMIC_TEMP_SUFFIX = /^[1-9][0-9]*-[0-9a-f]{36}$/u;
+function atomicTemporaryPrefix(name) {
+	return `.${name}.tmp-`;
+}
+function atomicTemporaryName(name, entropy) {
+	return `${atomicTemporaryPrefix(name)}${process.pid}-${entropy.toString("hex")}`;
+}
+/** Recognize only names produced by this writer for the specified target. */
+function isAtomicTemporaryName(candidate, name) {
+	const prefix = atomicTemporaryPrefix(name);
+	return candidate.startsWith(prefix) && ATOMIC_TEMP_SUFFIX.test(candidate.slice(prefix.length));
+}
+/** Publish exact bytes within one pinned parent. No failure is reported after rename commits. */
+async function atomicWriteFile(directory, name, bytes, options = {}) {
+	validateComponent(name);
+	const operations = {
+		open,
+		rename,
+		unlink,
+		randomBytes,
+		...options.operations
+	};
+	const signal = options.signal;
+	await directory.withHandle(async (parent, alias) => {
+		throwIfAborted(signal);
+		const target = `${alias}/${name}`;
+		const temporaryName = atomicTemporaryName(name, operations.randomBytes(18));
+		validateComponent(temporaryName);
+		const temporary = `${alias}/${temporaryName}`;
+		let handle;
+		let ownedIdentity;
+		let committed = false;
+		const rejectUnsafeTarget = async () => {
+			const stat = await directory.inspect(name, signal);
+			if (stat && !stat.isFile()) throw unsafeFilesystem("Atomic target is not a regular file.");
+		};
+		try {
+			await rejectUnsafeTarget();
+			throwIfAborted(signal);
+			handle = await operations.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, options.mode ?? 384);
+			ownedIdentity = await handle.stat({ bigint: true });
+			throwIfAborted(signal);
+			await handle.writeFile(bytes);
+			throwIfAborted(signal);
+			await syncFile(handle);
+			throwIfAborted(signal);
+			await handle.close();
+			handle = void 0;
+			await rejectUnsafeTarget();
+			const temporaryStat = await directory.inspect(temporaryName, signal);
+			if (!temporaryStat?.isFile() || temporaryStat.dev !== ownedIdentity.dev || temporaryStat.ino !== ownedIdentity.ino) throw unsafeFilesystem("Atomic temporary file was replaced.");
+			throwIfAborted(signal);
+			await operations.rename(temporary, target);
+			committed = true;
+			directory.markCommitted();
+		} catch (cause) {
+			if (handle) try {
+				await handle.close();
+			} catch {}
+			if (!committed && ownedIdentity) try {
+				const stat = await directory.inspect(temporaryName);
+				if (stat?.dev === ownedIdentity.dev && stat.ino === ownedIdentity.ino) await operations.unlink(temporary);
+			} catch {}
+			throw cause;
+		}
+		try {
+			await syncFile(parent);
+		} catch {}
+	});
+}
+//#endregion
+//#region src/ids.ts
+const SOURCE_ID_PATTERN = /^[0-9a-f]{64}$/u;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
+const WINDOWS_DRIVE_PATTERN = /^[a-zA-Z]:/u;
+function sourceId(value) {
+	if (!SOURCE_ID_PATTERN.test(value)) throw invalidPath("Source ID must be exactly 64 lowercase hexadecimal characters.");
+	return value;
+}
+function pageId(value) {
+	if (value.length === 0) throw invalidPath("Page ID must not be empty.");
+	if (value.startsWith("/") || value.startsWith("//") || WINDOWS_DRIVE_PATTERN.test(value)) throw invalidPath("Page ID must be a relative POSIX path.");
+	if (value.includes("\\")) throw invalidPath("Page ID must use POSIX separators.");
+	if (CONTROL_CHARACTER_PATTERN.test(value)) throw invalidPath("Page ID must not contain control characters.");
+	if (value.includes("%")) throw invalidPath("Page ID must not contain percent-encoded or ambiguous percent characters.");
+	if (value.toLowerCase().endsWith(".md")) throw invalidPath("Page ID must not include the .md extension.");
+	const segments = value.split("/");
+	if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) throw invalidPath("Page ID must not contain empty, current-directory, or parent-directory segments.");
+	return segments.join("/");
+}
+function isSourceId(value) {
+	return SOURCE_ID_PATTERN.test(value);
+}
+function isPageId(value) {
+	try {
+		pageId(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/markdown.ts
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+const UTF8_ENCODER = new TextEncoder();
+const FRONTMATTER_DELIMITER = "---";
+const KEY_LINE = /^([A-Za-z][A-Za-z0-9_-]*):(.*)$/u;
+const SOURCE_ITEM_LINE = /^  - (.+)$/u;
+const ATX_HEADING = /^(#{1,6})(?:[ \t]+(.*?)[ \t]*|[ \t]*)$/u;
+const FENCE_OPEN$1 = /^[ \t]{0,3}(`{3,}|~{3,})(.*)$/u;
+function invalidPage(message, cause) {
+	return new LlmWikiError("INVALID_PAGE", message, cause === void 0 ? void 0 : { cause });
+}
+function encodeUtf8(text) {
+	return UTF8_ENCODER.encode(text);
+}
+function decodeUtf8(bytes) {
+	try {
+		return UTF8_DECODER.decode(bytes);
+	} catch (cause) {
+		throw invalidPage("Wiki content is not valid UTF-8.", cause);
+	}
+}
+function normalizeLineEndings(value) {
+	return value.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+}
+function parseQuotedString(value, field) {
+	if (!value.startsWith("\"") || !value.endsWith("\"")) throw invalidPage(`Frontmatter ${field} must be a double-quoted string.`);
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch (cause) {
+		throw invalidPage(`Frontmatter ${field} contains an invalid quoted string.`, cause);
+	}
+	if (typeof parsed !== "string" || parsed.includes("\n") || parsed.includes("\r") || parsed.includes("\u2028") || parsed.includes("\u2029")) throw invalidPage(`Frontmatter ${field} must be a single-line string.`);
+	if (parsed.trim().length === 0) throw invalidPage(`Frontmatter ${field} must not be empty.`);
+	return parsed;
+}
+function parseSourceItem(value) {
+	if (!value.startsWith("\"") || !value.endsWith("\"")) throw invalidPage("Frontmatter source IDs must be double-quoted strings.");
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch (cause) {
+		throw invalidPage("Frontmatter contains an invalid quoted source ID.", cause);
+	}
+	if (typeof parsed !== "string") throw invalidPage("Frontmatter source IDs must be strings.");
+	try {
+		return sourceId(parsed);
+	} catch (cause) {
+		throw invalidPage("Frontmatter contains an invalid source ID.", cause);
+	}
+}
+function parseFrontmatter(lines) {
+	const values = {};
+	const seen = /* @__PURE__ */ new Set();
+	for (let index = 0; index < lines.length;) {
+		const line = lines[index];
+		if (line === void 0 || line.trim().length === 0) throw invalidPage("Frontmatter must not contain blank lines.");
+		const match = KEY_LINE.exec(line);
+		if (match === null) throw invalidPage("Frontmatter contains malformed YAML.");
+		const key = match[1];
+		const rawValue = match[2] ?? "";
+		if (key !== "title" && key !== "summary" && key !== "sources") throw invalidPage(`Frontmatter contains unknown key ${JSON.stringify(key)}.`);
+		if (seen.has(key)) throw invalidPage(`Frontmatter contains duplicate key ${JSON.stringify(key)}.`);
+		seen.add(key);
+		if (key === "sources") {
+			if (rawValue.length !== 0) throw invalidPage("Frontmatter sources must use a block list.");
+			const sources = [];
+			index += 1;
+			while (index < lines.length) {
+				const sourceLine = lines[index];
+				if (sourceLine === void 0) break;
+				const item = SOURCE_ITEM_LINE.exec(sourceLine);
+				if (item === null) break;
+				sources.push(parseSourceItem(item[1] ?? ""));
+				index += 1;
+			}
+			if (sources.length === 0) throw invalidPage("Frontmatter sources must not be empty.");
+			for (let sourceIndex = 1; sourceIndex < sources.length; sourceIndex += 1) {
+				const previous = sources[sourceIndex - 1];
+				const current = sources[sourceIndex];
+				if (previous === void 0 || current === void 0) throw invalidPage("Frontmatter source list is malformed.");
+				if (previous === current) throw invalidPage("Frontmatter source IDs must be unique.");
+				if (previous > current) throw invalidPage("Frontmatter source IDs must be sorted.");
+			}
+			values.sources = sources;
+			continue;
+		}
+		if (!rawValue.startsWith(" ")) throw invalidPage(`Frontmatter ${key} must have one value separator.`);
+		values[key] = parseQuotedString(rawValue.slice(1), key);
+		index += 1;
+	}
+	if (values.title === void 0 || values.summary === void 0 || values.sources === void 0) throw invalidPage("Frontmatter must contain title, summary, and sources.");
+	return {
+		title: values.title,
+		summary: values.summary,
+		sources: values.sources
+	};
+}
+function parsePageMarkdown(markdown) {
+	const lines = normalizeLineEndings(markdown).split("\n");
+	if (lines[0] !== FRONTMATTER_DELIMITER) throw invalidPage("Page must begin with YAML frontmatter.");
+	const closingIndex = lines.indexOf(FRONTMATTER_DELIMITER, 1);
+	if (closingIndex < 0) throw invalidPage("Page frontmatter is not closed.");
+	if (lines[closingIndex + 1] !== "") throw invalidPage("Page must contain one blank line after frontmatter.");
+	const metadata = parseFrontmatter(lines.slice(1, closingIndex));
+	const body = lines.slice(closingIndex + 2).join("\n").replace(/\n+$/u, "");
+	if (body.trim().length === 0) throw invalidPage("Page Markdown body must not be empty.");
+	return {
+		metadata,
+		body: `${body}\n`,
+		bodyStartLine: closingIndex + 3
+	};
+}
+function renderPageMarkdown(metadata, body) {
+	const title = parseQuotedString(JSON.stringify(metadata.title), "title");
+	const summary = parseQuotedString(JSON.stringify(metadata.summary), "summary");
+	if (metadata.sources.length === 0) throw invalidPage("Frontmatter sources must not be empty.");
+	const sources = metadata.sources.map((value) => {
+		try {
+			return sourceId(value);
+		} catch (cause) {
+			throw invalidPage("Frontmatter contains an invalid source ID.", cause);
+		}
+	}).sort();
+	if (new Set(sources).size !== sources.length) throw invalidPage("Frontmatter source IDs must be unique.");
+	const normalizedBody = normalizeLineEndings(body).replace(/\n+$/u, "");
+	if (normalizedBody.trim().length === 0) throw invalidPage("Page Markdown body must not be empty.");
+	const sourceLines = sources.map((value) => `  - ${JSON.stringify(value)}`).join("\n");
+	return `---\ntitle: ${JSON.stringify(title)}\nsummary: ${JSON.stringify(summary)}\nsources:\n${sourceLines}\n---\n\n${normalizedBody}\n`;
+}
+function splitMarkdownSections(body, firstLine = 1) {
+	if (!Number.isSafeInteger(firstLine) || firstLine < 1) throw invalidPage("Section start line must be a positive integer.");
+	const lines = normalizeLineEndings(body).replace(/\n+$/u, "").split("\n");
+	const sections = [];
+	const headingTrail = [];
+	let sectionStart = firstLine;
+	let sectionLines = [];
+	let fenceCharacter;
+	let fenceLength = 0;
+	const flush = () => {
+		const text = sectionLines.join("\n").trimEnd();
+		if (text.trim().length > 0 || headingTrail.length > 0) sections.push({
+			headingTrail: headingTrail.map(({ title }) => title),
+			startLine: sectionStart,
+			text
+		});
+		sectionLines = [];
+	};
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		if (fenceCharacter !== void 0) {
+			sectionLines.push(line);
+			if (new RegExp(`^[ \\t]{0,3}${fenceCharacter === "`" ? "`" : "~"}{${fenceLength},}[ \\t]*$`, "u").test(line)) fenceCharacter = void 0;
+			continue;
+		}
+		const fence = FENCE_OPEN$1.exec(line);
+		if (fence !== null) {
+			const marker = fence[1] ?? "";
+			fenceCharacter = marker[0];
+			fenceLength = marker.length;
+			sectionLines.push(line);
+			continue;
+		}
+		const heading = ATX_HEADING.exec(line);
+		if (heading === null) {
+			sectionLines.push(line);
+			continue;
+		}
+		flush();
+		const level = (heading[1] ?? "").length;
+		const rawHeading = (heading[2] ?? "").replace(/[ \t]+#+[ \t]*$/u, "").trim();
+		for (let ancestor = headingTrail.at(-1); ancestor !== void 0 && ancestor.level >= level; ancestor = headingTrail.at(-1)) headingTrail.pop();
+		headingTrail.push({
+			level,
+			title: rawHeading
+		});
+		sectionStart = firstLine + index;
+	}
+	flush();
+	return sections;
+}
+//#endregion
+//#region src/tokenizer.ts
+const TOKEN_RUN = /[\p{L}\p{N}]+/gu;
+const CJK_CHARACTER = /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]$/u;
+/**
+* Tokenizes normalized text deterministically. CJK-only runs are retained as a
+* token and, when longer than one code point, additionally produce overlapping
+* two-code-point grams. Mixed/non-CJK letter-number runs are emitted whole.
+*/
+function tokenize(value) {
+	const tokens = [];
+	visitNormalizedTokenSpans(value.normalize("NFKC").toLowerCase(), (term) => {
+		tokens.push(term);
+	});
+	return tokens;
+}
+/** Visits existing tokens in normalized text; offsets are UTF-16 slice boundaries. */
+function visitNormalizedTokenSpans(text, visit) {
+	for (const match of text.matchAll(TOKEN_RUN)) {
+		const run = match[0];
+		const start = match.index;
+		visit(run, start, start + run.length);
+		const characters = Array.from(run);
+		if (characters.length > 1 && characters.every((character) => CJK_CHARACTER.test(character))) {
+			let offset = start;
+			for (let index = 0; index + 1 < characters.length; index += 1) {
+				const gram = `${characters[index]}${characters[index + 1]}`;
+				visit(gram, offset, offset + gram.length);
+				offset += characters[index].length;
+			}
+		}
+	}
+}
+const HASH_PATTERN = /^[0-9a-f]{64}$/u;
+const K1 = 1.2;
+const B = .75;
+const BOOST_TITLE = 2;
+const BOOST_HEADING = 1.5;
+const BOOST_BODY = 1;
+const codeUnitCompare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+function sha256$1(bytes) {
+	const digest = createHash("sha256");
+	digest.update(bytes);
+	return digest.digest("hex");
+}
+const canonicalBytes = (value) => encodeUtf8(`${JSON.stringify(value, null, 2)}\n`);
+function corrupt(message, cause) {
+	return new LlmWikiError("INDEX_CORRUPT", message, cause === void 0 ? void 0 : { cause });
+}
+function exactObject(value, keys, name) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw corrupt(`${name} must be an object.`);
+	const object = value;
+	const actual = Object.keys(object);
+	if (actual.length !== keys.length || actual.some((key) => !keys.includes(key))) throw corrupt(`${name} contains missing or unknown fields.`);
+	return object;
+}
+function safeInteger(value, name, positive = false) {
+	if (!Number.isSafeInteger(value) || value < (positive ? 1 : 0)) throw corrupt(`${name} must be a ${positive ? "positive" : "non-negative"} safe integer.`);
+	return value;
+}
+function finiteAverage(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw corrupt("averageSectionLength must be finite and non-negative.");
+	return value;
+}
+function stringValue(value, name) {
+	if (typeof value !== "string") throw corrupt(`${name} must be a string.`);
+	return value;
+}
+function parseFingerprints(value, name) {
+	if (!Array.isArray(value)) throw corrupt(`${name} must be an array.`);
+	let previous;
+	return value.map((entry, index) => {
+		const object = exactObject(entry, ["pageId", "sha256"], `${name}[${index}]`);
+		const id = stringValue(object.pageId, `${name}[${index}].pageId`);
+		pageId(id);
+		const hash = stringValue(object.sha256, `${name}[${index}].sha256`);
+		if (!HASH_PATTERN.test(hash)) throw corrupt(`${name}[${index}].sha256 is invalid.`);
+		if (previous !== void 0 && codeUnitCompare(previous, id) >= 0) throw corrupt(`${name} must be uniquely sorted by pageId.`);
+		previous = id;
+		return {
+			pageId: id,
+			sha256: hash
+		};
+	});
+}
+function parseTermCounts(value, name) {
+	if (!Array.isArray(value)) throw corrupt(`${name} must be an array.`);
+	let previous;
+	return value.map((entry, index) => {
+		const object = exactObject(entry, ["term", "count"], `${name}[${index}]`);
+		const term = stringValue(object.term, `${name}[${index}].term`);
+		if (term.length === 0 || tokenize(term).length === 0) throw corrupt(`${name}[${index}].term is invalid.`);
+		if (previous !== void 0 && codeUnitCompare(previous, term) >= 0) throw corrupt(`${name} must be uniquely sorted by term.`);
+		previous = term;
+		return {
+			term,
+			count: safeInteger(object.count, `${name}[${index}].count`, true)
+		};
+	});
+}
+function stringArray(value, name) {
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw corrupt(`${name} must be a string array.`);
+	return value;
+}
+function parseSearchIndex(bytes) {
+	let value;
+	try {
+		value = JSON.parse(decodeUtf8(bytes));
+	} catch (cause) {
+		throw corrupt("search.json is malformed.", cause);
+	}
+	const root = exactObject(value, [
+		"formatVersion",
+		"pageFingerprints",
+		"documentCount",
+		"averageSectionLength",
+		"documentFrequencies",
+		"sections"
+	], "search.json");
+	if (root.formatVersion !== 1) throw corrupt("search.json has an incompatible format version.");
+	const pageFingerprints = parseFingerprints(root.pageFingerprints, "pageFingerprints");
+	const documentCount = safeInteger(root.documentCount, "documentCount");
+	const averageSectionLength = finiteAverage(root.averageSectionLength);
+	const documentFrequencies = parseTermCounts(root.documentFrequencies, "documentFrequencies");
+	if (!Array.isArray(root.sections)) throw corrupt("sections must be an array.");
+	let previousPage = "";
+	let previousLine = 0;
+	const sections = root.sections.map((entry, index) => {
+		const object = exactObject(entry, [
+			"pageId",
+			"title",
+			"headingTrail",
+			"startLine",
+			"sourceIds",
+			"normalizedText",
+			"length",
+			"titleTermFrequencies",
+			"headingTermFrequencies",
+			"bodyTermFrequencies"
+		], `sections[${index}]`);
+		const id = stringValue(object.pageId, `sections[${index}].pageId`);
+		pageId(id);
+		const startLine = safeInteger(object.startLine, `sections[${index}].startLine`, true);
+		if (codeUnitCompare(previousPage, id) > 0 || previousPage === id && previousLine >= startLine) throw corrupt("sections must be uniquely sorted by pageId and startLine.");
+		previousPage = id;
+		previousLine = startLine;
+		const sourceIds = stringArray(object.sourceIds, `sections[${index}].sourceIds`);
+		let priorSource;
+		for (const idValue of sourceIds) {
+			sourceId(idValue);
+			if (priorSource !== void 0 && codeUnitCompare(priorSource, idValue) >= 0) throw corrupt("section sourceIds must be uniquely sorted.");
+			priorSource = idValue;
+		}
+		return {
+			pageId: id,
+			title: stringValue(object.title, `sections[${index}].title`),
+			headingTrail: stringArray(object.headingTrail, `sections[${index}].headingTrail`),
+			startLine,
+			sourceIds,
+			normalizedText: stringValue(object.normalizedText, `sections[${index}].normalizedText`),
+			length: safeInteger(object.length, `sections[${index}].length`),
+			titleTermFrequencies: parseTermCounts(object.titleTermFrequencies, `sections[${index}].titleTermFrequencies`),
+			headingTermFrequencies: parseTermCounts(object.headingTermFrequencies, `sections[${index}].headingTermFrequencies`),
+			bodyTermFrequencies: parseTermCounts(object.bodyTermFrequencies, `sections[${index}].bodyTermFrequencies`)
+		};
+	});
+	if (documentCount !== sections.length) throw corrupt("documentCount does not match sections.");
+	return {
+		formatVersion: 1,
+		pageFingerprints,
+		documentCount,
+		averageSectionLength,
+		documentFrequencies,
+		sections
+	};
+}
+function parseIndexState(bytes) {
+	let value;
+	try {
+		value = JSON.parse(decodeUtf8(bytes));
+	} catch (cause) {
+		throw corrupt("state.json is malformed.", cause);
+	}
+	const root = exactObject(value, [
+		"formatVersion",
+		"pages",
+		"searchSha256"
+	], "state.json");
+	if (root.formatVersion !== 1) throw corrupt("state.json has an incompatible format version.");
+	const searchHash = stringValue(root.searchSha256, "searchSha256");
+	if (!HASH_PATTERN.test(searchHash)) throw corrupt("searchSha256 is invalid.");
+	return {
+		formatVersion: 1,
+		pages: parseFingerprints(root.pages, "pages"),
+		searchSha256: searchHash
+	};
+}
+async function pinned(paths, signal, root, callback) {
+	if (root !== void 0) return callback(root);
+	const result = await withWikiRoot(paths.authority, { signal }, callback);
+	if (result === null) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki root is missing.");
+	return result;
+}
+async function discoverDirectory(directory, pagesRoot, paths, root, signal) {
+	const result = await root.directory(wikiRelativeSegments(paths, directory), { signal }, async (held) => {
+		const pages = [];
+		for (const entry of await held.list(signal)) {
+			throwIfAborted(signal);
+			const path = join(directory, entry.name);
+			if (entry.stat.isSymbolicLink()) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Symbolic links are not allowed in the pages tree.");
+			if (entry.stat.isDirectory()) pages.push(...await discoverDirectory(path, pagesRoot, paths, root, signal));
+			else if (entry.stat.isFile() && entry.name.endsWith(".md")) pages.push({
+				...entry,
+				path,
+				key: relative(pagesRoot, path).split(sep).join("/")
+			});
+			if (!await root.validate(entry, signal)) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki page identity changed during discovery.");
+		}
+		return pages.sort((a, b) => codeUnitCompare(a.key, b.key));
+	});
+	if (result === null) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki pages directory is missing.");
+	return result;
+}
+function sameStableFileSnapshot(before, after) {
+	return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs;
+}
+const corpusSnapshots = /* @__PURE__ */ new WeakMap();
+function samePathIdentity(snapshot, current) {
+	return current.isFile() && !current.isSymbolicLink() && sameStableFileSnapshot(snapshot, current);
+}
+async function validatePageSnapshot(page, root, signal) {
+	if (!await root.validate(page, signal)) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki page changed while the corpus was being read.");
+}
+async function validateCorpusSnapshot(snapshot, paths, root, signal) {
+	try {
+		throwIfAborted(signal);
+		const currentPages = await discoverDirectory(paths.pages, paths.pages, paths, root, signal);
+		if (currentPages.length !== snapshot.pages.length) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki page membership changed while the corpus was being read.");
+		for (let index = 0; index < snapshot.pages.length; index += 1) {
+			const expected = snapshot.pages[index];
+			const current = currentPages[index];
+			if (current.key !== expected.key || current.path !== expected.path || !samePathIdentity(expected.stat, current.stat)) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki page changed while the corpus was being read.");
+		}
+	} catch (cause) {
+		throwIfAborted(signal);
+		if (cause instanceof LlmWikiError) throw cause;
+		throw new LlmWikiError("UNSAFE_FILESYSTEM", "Unable to validate a stable wiki corpus.", { cause });
+	}
+}
+async function readSafePage(path, paths, root, signal, onExamined) {
+	try {
+		const segments = wikiRelativeSegments(paths, path);
+		const read = await root.directory(segments.slice(0, -1), { signal }, (parent) => parent.read(segments.at(-1), signal));
+		if (read === null) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Wiki page disappeared while being read.");
+		onExamined?.(path);
+		throwIfAborted(signal);
+		const snapshot = {
+			...read.snapshot,
+			path,
+			key: relative(paths.pages, path).split(sep).join("/")
+		};
+		await validatePageSnapshot(snapshot, root, signal);
+		return {
+			bytes: read.bytes,
+			snapshot
+		};
+	} catch (cause) {
+		throwIfAborted(signal);
+		if (cause instanceof LlmWikiError) throw cause;
+		throw new LlmWikiError("UNSAFE_FILESYSTEM", "Unable to read a wiki page safely.", { cause });
+	}
+}
+function frequencies(tokens) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
+	return [...counts].sort(([a], [b]) => codeUnitCompare(a, b)).map(([term, count]) => ({
+		term,
+		count
+	}));
+}
+function normalizeText(text) {
+	return text.normalize("NFKC").toLowerCase();
+}
+function buildSearchIndexFromPages(pages) {
+	const pageFingerprints = pages.map(({ pageId, bytes }) => ({
+		pageId,
+		sha256: sha256$1(bytes)
+	})).sort((a, b) => codeUnitCompare(a.pageId, b.pageId));
+	const pagesById = new Map(pages.map((page) => [page.pageId, page]));
+	const sections = [];
+	const documentFrequency = /* @__PURE__ */ new Map();
+	for (const fingerprint of pageFingerprints) {
+		const page = pagesById.get(fingerprint.pageId);
+		for (const section of splitMarkdownSections(page.body, page.bodyStartLine)) {
+			const titleTokens = tokenize(page.title);
+			const headingTokens = tokenize(section.headingTrail.join(" "));
+			const bodyTokens = tokenize(section.text);
+			const sectionTokens = [...headingTokens, ...bodyTokens];
+			const indexedTokens = [...titleTokens, ...sectionTokens];
+			for (const term of new Set(indexedTokens)) documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+			sections.push({
+				pageId: fingerprint.pageId,
+				title: page.title,
+				headingTrail: [...section.headingTrail],
+				startLine: section.startLine,
+				sourceIds: [...page.sourceIds].sort(codeUnitCompare),
+				normalizedText: normalizeText(section.text),
+				length: sectionTokens.length,
+				titleTermFrequencies: frequencies(titleTokens),
+				headingTermFrequencies: frequencies(headingTokens),
+				bodyTermFrequencies: frequencies(bodyTokens)
+			});
+		}
+	}
+	sections.sort((a, b) => codeUnitCompare(a.pageId, b.pageId) || a.startLine - b.startLine);
+	const documentCount = sections.length;
+	const search = {
+		formatVersion: 1,
+		pageFingerprints,
+		documentCount,
+		averageSectionLength: documentCount === 0 ? 0 : sections.reduce((sum, section) => sum + section.length, 0) / documentCount,
+		documentFrequencies: [...documentFrequency].sort(([a], [b]) => codeUnitCompare(a, b)).map(([term, count]) => ({
+			term,
+			count
+		})),
+		sections
+	};
+	const searchBytes = canonicalBytes(search);
+	const state = {
+		formatVersion: 1,
+		pages: pageFingerprints,
+		searchSha256: sha256$1(searchBytes)
+	};
+	return {
+		state,
+		search,
+		searchBytes,
+		stateBytes: canonicalBytes(state)
+	};
+}
+async function buildSearchIndex(paths, signal, onPageExamined, root) {
+	return pinned(paths, signal, root, async (held) => {
+		const discovered = await discoverDirectory(paths.pages, paths.pages, paths, held, signal);
+		const pages = [];
+		const pageSnapshots = [];
+		for (const page of discovered) {
+			const { bytes, snapshot } = await readSafePage(page.path, paths, held, signal, onPageExamined);
+			pageSnapshots.push(snapshot);
+			const id = pageId(page.key.replace(/\.md$/u, ""));
+			const parsed = parsePageMarkdown(decodeUtf8(bytes));
+			pages.push({
+				pageId: id,
+				bytes,
+				title: parsed.metadata.title,
+				sourceIds: parsed.metadata.sources,
+				body: parsed.body,
+				bodyStartLine: parsed.bodyStartLine
+			});
+		}
+		const corpusSnapshot = { pages: pageSnapshots };
+		const built = buildSearchIndexFromPages(pages);
+		await validateCorpusSnapshot(corpusSnapshot, paths, held, signal);
+		corpusSnapshots.set(built, corpusSnapshot);
+		return built;
+	});
+}
+function trustedSearchIndex(searchBytes, stateBytes, expected) {
+	const search = parseSearchIndex(searchBytes);
+	parseIndexState(stateBytes);
+	const searchMatches = searchBytes.byteLength === expected.searchBytes.byteLength && searchBytes.every((byte, index) => byte === expected.searchBytes[index]);
+	const stateMatches = stateBytes.byteLength === expected.stateBytes.byteLength && stateBytes.every((byte, index) => byte === expected.stateBytes[index]);
+	return searchMatches && stateMatches ? search : null;
+}
+async function validateBuiltIndexSnapshot(paths, built, signal, root) {
+	const snapshot = corpusSnapshots.get(built);
+	if (snapshot !== void 0) await pinned(paths, signal, root, (held) => validateCorpusSnapshot(snapshot, paths, held, signal));
+}
+async function writeIndex(paths, built, signal, root) {
+	await pinned(paths, signal, root, async (held) => {
+		await validateBuiltIndexSnapshot(paths, built, signal, held);
+		await held.directory(wikiRelativeSegments(paths, paths.index), {
+			create: true,
+			signal
+		}, async (index) => {
+			await validateBuiltIndexSnapshot(paths, built, signal, held);
+			await atomicWriteFile(index, "search.json", built.searchBytes, { signal });
+			throwIfAborted(signal);
+			await validateBuiltIndexSnapshot(paths, built, signal, held);
+			await atomicWriteFile(index, "state.json", built.stateBytes, { signal });
+			await validateBuiltIndexSnapshot(paths, built, signal, held);
+		});
+	});
+}
+function countFor(items, term) {
+	return items.find((item) => item.term === term)?.count ?? 0;
+}
+function utf8Snippet(text, maxBytes) {
+	const lines = text.split("\n");
+	let result = "";
+	for (const line of lines) {
+		const candidate = result.length === 0 ? line : `${result}\n${line}`;
+		if (encodeUtf8(candidate).byteLength <= maxBytes) {
+			result = candidate;
+			continue;
+		}
+		if (result.length > 0) break;
+		for (const character of line) {
+			if (encodeUtf8(result + character).byteLength > maxBytes) break;
+			result += character;
+		}
+		break;
+	}
+	return result;
+}
+function querySnippet(section, queryTerms, maxBytes) {
+	const text = section.normalizedText;
+	const terms = new Set(queryTerms.filter((term) => countFor(section.bodyTermFrequencies, term) > 0 && Buffer.byteLength(term, "utf8") <= maxBytes));
+	let selected;
+	if (terms.size > 0) visitNormalizedTokenSpans(text, (term, start, end) => {
+		if (terms.has(term) && (!selected || start < selected.start || start === selected.start && codeUnitCompare(term, selected.term) < 0)) selected = {
+			term,
+			start,
+			end
+		};
+	});
+	if (!selected) return utf8Snippet(text, maxBytes);
+	let start = selected.start;
+	let end = selected.end;
+	let remaining = maxBytes - Buffer.byteLength(selected.term, "utf8");
+	const extendLeft = (budget) => {
+		let used = 0;
+		while (start > 0) {
+			const last = text.charCodeAt(start - 1);
+			const previous = start - (last >= 56320 && last <= 57343 ? 2 : 1);
+			const bytes = Buffer.byteLength(text.slice(previous, start), "utf8");
+			if (used + bytes > budget) break;
+			start = previous;
+			used += bytes;
+		}
+		return used;
+	};
+	remaining -= extendLeft(Math.floor(remaining / 2));
+	while (end < text.length) {
+		const next = end + (text.codePointAt(end) > 65535 ? 2 : 1);
+		const bytes = Buffer.byteLength(text.slice(end, next), "utf8");
+		if (bytes > remaining) break;
+		end = next;
+		remaining -= bytes;
+	}
+	extendLeft(remaining);
+	return text.slice(start, end);
+}
+function searchBuiltIndex(index, query, options) {
+	throwIfAborted(options.signal);
+	if (!Number.isSafeInteger(options.limit) || options.limit < 1 || !Number.isSafeInteger(options.maxResults) || options.maxResults < 1 || !Number.isSafeInteger(options.maxSnippetBytes) || options.maxSnippetBytes < 1) throw new LlmWikiError("LIMIT_EXCEEDED", "Search limits must be positive safe integers.");
+	const queryTerms = [...new Set(tokenize(query))];
+	if (queryTerms.length === 0) throw new LlmWikiError("INVALID_PAGE", "Search query must contain at least one Unicode letter or number.");
+	const limit = Math.min(options.limit, options.maxResults);
+	const hits = [];
+	for (const section of index.sections) {
+		throwIfAborted(options.signal);
+		let score = 0;
+		for (const term of queryTerms) {
+			const df = countFor(index.documentFrequencies, term);
+			if (df === 0) continue;
+			const weightedFrequency = BOOST_TITLE * countFor(section.titleTermFrequencies, term) + BOOST_HEADING * countFor(section.headingTermFrequencies, term) + BOOST_BODY * countFor(section.bodyTermFrequencies, term);
+			if (weightedFrequency === 0) continue;
+			const idf = Math.log(1 + (index.documentCount - df + .5) / (df + .5));
+			const normalization = index.averageSectionLength === 0 ? 1 : 1 - B + B * section.length / index.averageSectionLength;
+			score += idf * (weightedFrequency * 2.2) / (weightedFrequency + K1 * normalization);
+		}
+		if (!Number.isFinite(score)) throw corrupt("Search produced a non-finite score.");
+		if (score > 0) hits.push({
+			section,
+			score
+		});
+	}
+	hits.sort((a, b) => b.score - a.score || codeUnitCompare(a.section.pageId, b.section.pageId) || a.section.startLine - b.section.startLine);
+	return hits.slice(0, limit).map(({ section, score }) => ({
+		pageId: pageId(section.pageId),
+		title: section.title,
+		headingTrail: section.headingTrail,
+		startLine: section.startLine,
+		score,
+		snippet: querySnippet(section, queryTerms, options.maxSnippetBytes),
+		sourceIds: section.sourceIds.map(sourceId)
+	}));
+}
+//#endregion
+//#region src/lint.ts
+const HASH$1 = /^[0-9a-f]{64}$/u;
+const TEMP_FILE = /^\..+\.tmp-\d+-[0-9a-f]+$/u;
+const EXTERNAL_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/u;
+const FENCE_OPEN = /^[ \t]{0,3}(`{3,}|~{3,})/u;
+const MARKDOWN_LINK = /(?<!!)\[[^\]]*\]\(([^\s)]+)(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\)/gu;
+const WIKILINK = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/gu;
+function compareCodeUnits$1(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+function relativePath(paths, path) {
+	const value = relative(paths.root, path).split(sep).join("/");
+	return value.length === 0 ? "." : value;
+}
+function diagnostic(context, code, severity, path, message, line) {
+	context.diagnostics.push(line === void 0 ? {
+		code,
+		severity,
+		path: relativePath(context.paths, path),
+		message
+	} : {
+		code,
+		severity,
+		path: relativePath(context.paths, path),
+		line,
+		message
+	});
+}
+function sha256(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+async function stat(path, context) {
+	const segments = wikiRelativeSegments(context.paths, path);
+	if (segments.length === 0) return {
+		isDirectory: () => true,
+		isSymbolicLink: () => false,
+		isFile: () => false
+	};
+	return context.root.directory(segments.slice(0, -1), { signal: context.signal }, (parent) => parent.inspect(segments.at(-1), context.signal));
+}
+async function readBytes$1(path, context) {
+	const segments = wikiRelativeSegments(context.paths, path);
+	const read = await context.root.directory(segments.slice(0, -1), { signal: context.signal }, (parent) => parent.read(segments.at(-1), context.signal));
+	if (read === null) return null;
+	context.examinedPaths.add(path);
+	throwIfAborted(context.signal);
+	return read.bytes;
+}
+async function entries(path, context) {
+	const listed = await context.root.directory(wikiRelativeSegments(context.paths, path), { signal: context.signal }, (parent) => parent.list(context.signal));
+	if (listed === null) return [];
+	return listed.map(({ name, stat }) => ({
+		name,
+		isSymbolicLink: () => stat.isSymbolicLink(),
+		isDirectory: () => stat.isDirectory(),
+		isFile: () => stat.isFile()
+	}));
+}
+async function inspectRequiredDirectory(path, context) {
+	const info = await stat(path, context);
+	if (info === null) {
+		diagnostic(context, "REQUIRED_DIRECTORY_MISSING", "error", path, "Required wiki directory is missing.");
+		return false;
+	}
+	if (info.isSymbolicLink()) return false;
+	if (!info.isDirectory()) {
+		diagnostic(context, "REQUIRED_PATH_NOT_DIRECTORY", "error", path, "Required wiki path is not a directory.");
+		return false;
+	}
+	return true;
+}
+async function scanTempsAndSymlinks(path, context) {
+	const info = await stat(path, context);
+	if (info === null || !info.isDirectory() || info.isSymbolicLink()) return;
+	for (const entry of await entries(path, context)) {
+		const child = join(path, entry.name);
+		if (entry.isSymbolicLink()) {
+			diagnostic(context, "UNSAFE_SYMLINK", "error", child, "Symbolic links are not allowed in the wiki.");
+			continue;
+		}
+		if (entry.isDirectory()) {
+			await scanTempsAndSymlinks(child, context);
+			continue;
+		}
+		if (TEMP_FILE.test(entry.name)) diagnostic(context, "TEMP_FILE_ABANDONED", "warning", child, "Abandoned atomic-write temporary file.");
+	}
+}
+function validSourceMetadata(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const object = value;
+	return typeof object.id === "string" && isSourceId(object.id) && typeof object.name === "string" && object.name.trim().length > 0 && typeof object.mediaType === "string" && object.mediaType.trim().length > 0 && Number.isSafeInteger(object.byteCount) && object.byteCount >= 0 && typeof object.capturedAt === "string" && !Number.isNaN(Date.parse(object.capturedAt)) && new Date(object.capturedAt).toISOString() === object.capturedAt && (object.origin === void 0 || typeof object.origin === "string" && object.origin.trim().length > 0);
+}
+async function inspectSources(context) {
+	const validSources = /* @__PURE__ */ new Set();
+	if (!await inspectRequiredDirectory(context.paths.sources, context)) return validSources;
+	for (const entry of await entries(context.paths.sources, context)) {
+		const directory = join(context.paths.sources, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (!entry.isDirectory() || !isSourceId(entry.name)) {
+			diagnostic(context, "SOURCE_INVALID_ID", "error", directory, "Source directory name must be a lowercase SHA-256 ID.");
+			continue;
+		}
+		const contentPath = join(directory, "content");
+		const contentStat = await stat(contentPath, context);
+		let content = null;
+		if (contentStat === null) diagnostic(context, "SOURCE_CONTENT_MISSING", "error", contentPath, "Source content is missing.");
+		else if (contentStat.isSymbolicLink()) {} else if (!contentStat.isFile()) diagnostic(context, "SOURCE_CONTENT_NOT_FILE", "error", contentPath, "Source content must be a regular file.");
+		else content = await readBytes$1(contentPath, context);
+		if (content !== null && sha256(content) !== entry.name) diagnostic(context, "SOURCE_HASH_MISMATCH", "error", contentPath, "Source ID does not match the SHA-256 hash of content.");
+		const metadataPath = join(directory, "metadata.json");
+		const metadataStat = await stat(metadataPath, context);
+		let metadata = null;
+		if (metadataStat === null) diagnostic(context, "SOURCE_METADATA_MISSING", "error", metadataPath, "Source metadata is missing.");
+		else if (metadataStat.isSymbolicLink()) {} else if (!metadataStat.isFile()) diagnostic(context, "SOURCE_METADATA_NOT_FILE", "error", metadataPath, "Source metadata must be a regular file.");
+		else {
+			const bytes = await readBytes$1(metadataPath, context);
+			if (bytes !== null) try {
+				const parsed = JSON.parse(decodeUtf8(bytes));
+				if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+					const allowed = {
+						id: true,
+						name: true,
+						mediaType: true,
+						byteCount: true,
+						capturedAt: true,
+						origin: true
+					};
+					for (const key of Object.keys(parsed).sort(compareCodeUnits$1)) if (allowed[key] !== true) diagnostic(context, "SOURCE_METADATA_UNKNOWN_KEY", "error", metadataPath, `Source metadata contains unknown key ${JSON.stringify(key)}.`);
+				}
+				if (!validSourceMetadata(parsed)) diagnostic(context, "SOURCE_METADATA_INVALID", "error", metadataPath, "Source metadata does not match the required schema.");
+				else metadata = parsed;
+			} catch {
+				diagnostic(context, "SOURCE_METADATA_MALFORMED", "error", metadataPath, "Source metadata is not valid UTF-8 JSON.");
+			}
+		}
+		if (metadata !== null && metadata.id !== entry.name) diagnostic(context, "SOURCE_METADATA_ID_MISMATCH", "error", metadataPath, "Source metadata ID does not match its directory name.");
+		if (metadata !== null && content !== null && metadata.byteCount !== content.byteLength) diagnostic(context, "SOURCE_METADATA_BYTE_COUNT_MISMATCH", "error", metadataPath, "Source metadata byteCount does not match content bytes.");
+		if (content !== null && sha256(content) === entry.name && metadata !== null && metadata.id === entry.name && metadata.byteCount === content.byteLength) validSources.add(entry.name);
+	}
+	return validSources;
+}
+async function collectPageFiles(directory, context, output) {
+	for (const entry of await entries(directory, context)) {
+		const path = join(directory, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) await collectPageFiles(path, context, output);
+		else output.push(path);
+	}
+}
+function linkTargets(body, firstLine) {
+	const result = [];
+	const lines = body.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+	let fence = null;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		if (fence !== null) {
+			if (new RegExp(`^[ \\t]{0,3}${fence.character === "`" ? "`" : "~"}{${fence.length},}[ \\t]*$`, "u").test(line)) fence = null;
+			continue;
+		}
+		const opening = FENCE_OPEN.exec(line);
+		if (opening !== null) {
+			const marker = opening[1] ?? "";
+			fence = {
+				character: marker[0] ?? "`",
+				length: marker.length
+			};
+			continue;
+		}
+		for (const match of line.matchAll(MARKDOWN_LINK)) result.push({
+			target: match[1] ?? "",
+			line: firstLine + index,
+			wiki: false
+		});
+		for (const match of line.matchAll(WIKILINK)) result.push({
+			target: match[1]?.trim() ?? "",
+			line: firstLine + index,
+			wiki: true
+		});
+	}
+	return result;
+}
+function validateLinks(page, pageIds, context) {
+	const linkedPages = /* @__PURE__ */ new Set();
+	const pageDirectory = posix.dirname(page.id);
+	for (const link of linkTargets(page.body, page.bodyStartLine)) {
+		let target = link.target;
+		if (target.length === 0 || target.startsWith("#") || target.startsWith("//") || EXTERNAL_SCHEME.test(target)) continue;
+		target = target.split("#", 1)[0] ?? "";
+		target = target.split("?", 1)[0] ?? "";
+		if (target.length === 0) continue;
+		const hadExtension = target.toLowerCase().endsWith(".md");
+		if (hadExtension) target = target.slice(0, -3);
+		const resolved = posix.normalize(posix.join(pageDirectory, target));
+		if (resolved === ".." || resolved.startsWith("../") || target.startsWith("/") || target.includes("\\")) {
+			diagnostic(context, "LINK_ESCAPES_PAGES", "error", page.path, "Relative page link escapes the pages directory.", link.line);
+			continue;
+		}
+		if (!isPageId(resolved) || !hadExtension && !link.wiki) continue;
+		if (!pageIds.has(resolved)) diagnostic(context, "BROKEN_PAGE_LINK", "error", page.path, `Linked page ${JSON.stringify(resolved)} does not exist.`, link.line);
+		else if (resolved !== page.id) linkedPages.add(resolved);
+	}
+	return linkedPages;
+}
+async function inspectPages(validSources, context) {
+	const pages = [];
+	const referencedSources = /* @__PURE__ */ new Set();
+	if (!await inspectRequiredDirectory(context.paths.pages, context)) return referencedSources;
+	const files = [];
+	await collectPageFiles(context.paths.pages, context, files);
+	files.sort(compareCodeUnits$1);
+	for (const path of files) {
+		const logical = relative(context.paths.pages, path).split(sep).join("/");
+		if (extname(logical) !== ".md" || !isPageId(logical.slice(0, -3))) {
+			diagnostic(context, "PAGE_INVALID_PATH", "error", path, "Page path must be a normalized relative path ending in lowercase .md.");
+			continue;
+		}
+		const bytes = await readBytes$1(path, context);
+		if (bytes === null) continue;
+		try {
+			const parsed = parsePageMarkdown(decodeUtf8(bytes));
+			const canonical = Buffer.from(encodeUtf8(renderPageMarkdown(parsed.metadata, parsed.body))).equals(Buffer.from(bytes));
+			if (!canonical) diagnostic(context, "PAGE_INVALID_MARKDOWN", "error", path, "Page is not valid canonical wiki Markdown.");
+			for (const source of parsed.metadata.sources) if (!validSources.has(source)) diagnostic(context, "PAGE_MISSING_SOURCE", "error", path, `Page references missing or invalid source ${JSON.stringify(source)}.`);
+			else if (canonical) referencedSources.add(source);
+			pages.push({
+				id: logical.slice(0, -3),
+				path,
+				bytes,
+				title: parsed.metadata.title,
+				sourceIds: parsed.metadata.sources,
+				body: parsed.body,
+				bodyStartLine: parsed.bodyStartLine
+			});
+		} catch {
+			diagnostic(context, "PAGE_INVALID_MARKDOWN", "error", path, "Page is not valid canonical wiki Markdown.");
+		}
+	}
+	const titles = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const normalized = page.title.normalize("NFKC").toLowerCase();
+		const group = titles.get(normalized) ?? [];
+		group.push(page);
+		titles.set(normalized, group);
+	}
+	for (const group of titles.values()) {
+		if (group.length < 2) continue;
+		for (const page of group) diagnostic(context, "DUPLICATE_TITLE", "warning", page.path, "Page title duplicates another title after Unicode normalization.");
+	}
+	const pageIds = new Set(pages.map(({ id }) => id));
+	const inbound = /* @__PURE__ */ new Set();
+	for (const page of pages) for (const target of validateLinks(page, pageIds, context)) inbound.add(target);
+	if (pages.length > 1) {
+		for (const page of pages) if (!inbound.has(page.id)) diagnostic(context, "ORPHAN_PAGE", "warning", page.path, "Page has no incoming links from another page.");
+	}
+	return referencedSources;
+}
+function exactKeys(value, keys) {
+	return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function safeNonnegativeInteger(value) {
+	return Number.isSafeInteger(value) && value >= 0;
+}
+function positiveInteger(value) {
+	return Number.isSafeInteger(value) && value > 0;
+}
+function sortedUniqueStrings(value) {
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return false;
+	let previous;
+	for (const item of value) {
+		if (previous !== void 0 && previous >= item) return false;
+		previous = item;
+	}
+	return true;
+}
+function validFrequencyArray(value) {
+	if (!Array.isArray(value)) return false;
+	let previousTerm;
+	for (const item of value) {
+		if (!record(item) || !exactKeys(item, ["term", "count"]) || typeof item.term !== "string" || item.term.length === 0 || !positiveInteger(item.count)) return false;
+		if (previousTerm !== void 0 && previousTerm >= item.term) return false;
+		previousTerm = item.term;
+	}
+	return true;
+}
+function validFingerprints(value) {
+	if (!Array.isArray(value)) return false;
+	let previousPageId;
+	for (const item of value) {
+		if (!record(item) || !exactKeys(item, ["pageId", "sha256"]) || typeof item.pageId !== "string" || !isPageId(item.pageId) || typeof item.sha256 !== "string" || !HASH$1.test(item.sha256)) return false;
+		if (previousPageId !== void 0 && previousPageId >= item.pageId) return false;
+		previousPageId = item.pageId;
+	}
+	return true;
+}
+function validState(value) {
+	return record(value) && exactKeys(value, [
+		"formatVersion",
+		"pages",
+		"searchSha256"
+	]) && value.formatVersion === 1 && validFingerprints(value.pages) && typeof value.searchSha256 === "string" && HASH$1.test(value.searchSha256);
+}
+function validSearch(value) {
+	if (!record(value) || !exactKeys(value, [
+		"formatVersion",
+		"pageFingerprints",
+		"documentCount",
+		"averageSectionLength",
+		"documentFrequencies",
+		"sections"
+	]) || value.formatVersion !== 1 || !validFingerprints(value.pageFingerprints) || !safeNonnegativeInteger(value.documentCount) || typeof value.averageSectionLength !== "number" || !Number.isFinite(value.averageSectionLength) || value.averageSectionLength < 0 || !validFrequencyArray(value.documentFrequencies) || !Array.isArray(value.sections)) return false;
+	let previous;
+	for (const item of value.sections) {
+		if (!record(item) || !exactKeys(item, [
+			"pageId",
+			"title",
+			"headingTrail",
+			"startLine",
+			"sourceIds",
+			"normalizedText",
+			"length",
+			"titleTermFrequencies",
+			"headingTermFrequencies",
+			"bodyTermFrequencies"
+		]) || typeof item.pageId !== "string" || !isPageId(item.pageId) || typeof item.title !== "string" || !Array.isArray(item.headingTrail) || !item.headingTrail.every((part) => typeof part === "string") || !positiveInteger(item.startLine) || !sortedUniqueStrings(item.sourceIds) || !item.sourceIds.every(isSourceId) || typeof item.normalizedText !== "string" || !safeNonnegativeInteger(item.length) || !validFrequencyArray(item.titleTermFrequencies) || !validFrequencyArray(item.headingTermFrequencies) || !validFrequencyArray(item.bodyTermFrequencies)) return false;
+		if (previous !== void 0 && (previous.pageId > item.pageId || previous.pageId === item.pageId && previous.startLine >= item.startLine)) return false;
+		previous = {
+			pageId: item.pageId,
+			startLine: item.startLine
+		};
+	}
+	return value.documentCount === value.sections.length;
+}
+async function inspectIndex(context) {
+	const indexStat = await stat(context.paths.index, context);
+	if (indexStat === null) {
+		diagnostic(context, "INDEX_MISSING", "warning", context.paths.index, "Derived search index is missing.");
+		return;
+	}
+	if (indexStat.isSymbolicLink()) return;
+	if (!indexStat.isDirectory()) {
+		diagnostic(context, "REQUIRED_PATH_NOT_DIRECTORY", "error", context.paths.index, "Required wiki path is not a directory.");
+		return;
+	}
+	const statePath = context.paths.indexFile("state.json");
+	const searchPath = context.paths.indexFile("search.json");
+	const [stateStat, searchStat] = await allSettledOnFailure([stat(statePath, context), stat(searchPath, context)]);
+	if (stateStat?.isSymbolicLink() === true || searchStat?.isSymbolicLink() === true) return;
+	if (stateStat === null || searchStat === null) {
+		diagnostic(context, "INDEX_MISSING", "warning", context.paths.index, "Derived search index is missing.");
+		return;
+	}
+	const [stateBytes, searchBytes] = await allSettledOnFailure([readBytes$1(statePath, context), readBytes$1(searchPath, context)]);
+	if (stateBytes === null || searchBytes === null) {
+		diagnostic(context, "INDEX_MISSING", "warning", context.paths.index, "Derived search index is missing.");
+		return;
+	}
+	let stateUnknown;
+	let searchUnknown;
+	try {
+		stateUnknown = JSON.parse(decodeUtf8(stateBytes));
+	} catch {
+		diagnostic(context, "INDEX_MALFORMED", "error", statePath, "Index state is not valid UTF-8 JSON.");
+		return;
+	}
+	try {
+		searchUnknown = JSON.parse(decodeUtf8(searchBytes));
+	} catch {
+		diagnostic(context, "INDEX_MALFORMED", "error", searchPath, "Search index is not valid UTF-8 JSON.");
+		return;
+	}
+	if (record(stateUnknown) && Object.hasOwn(stateUnknown, "formatVersion") && stateUnknown.formatVersion !== 1) {
+		diagnostic(context, "INDEX_INCOMPATIBLE", "error", statePath, "Index state uses an unsupported format version.");
+		return;
+	}
+	if (record(searchUnknown) && Object.hasOwn(searchUnknown, "formatVersion") && searchUnknown.formatVersion !== 1) {
+		diagnostic(context, "INDEX_INCOMPATIBLE", "error", searchPath, "Search index uses an unsupported format version.");
+		return;
+	}
+	if (!validState(stateUnknown)) {
+		diagnostic(context, "INDEX_MALFORMED", "error", statePath, "Index state does not match formatVersion 1.");
+		return;
+	}
+	if (!validSearch(searchUnknown)) {
+		diagnostic(context, "INDEX_MALFORMED", "error", searchPath, "Search index does not match formatVersion 1.");
+		return;
+	}
+	if (`${JSON.stringify(stateUnknown, null, 2)}\n` !== decodeUtf8(stateBytes)) {
+		diagnostic(context, "INDEX_MALFORMED", "error", statePath, "Index state is not canonically serialized.");
+		return;
+	}
+	if (`${JSON.stringify(searchUnknown, null, 2)}\n` !== decodeUtf8(searchBytes)) {
+		diagnostic(context, "INDEX_MALFORMED", "error", searchPath, "Search index is not canonically serialized.");
+		return;
+	}
+	try {
+		const expected = await buildSearchIndex(context.paths, context.signal, (path) => context.examinedPaths.add(path), context.root);
+		const matches = trustedSearchIndex(searchBytes, stateBytes, expected) !== null;
+		await validateBuiltIndexSnapshot(context.paths, expected, context.signal, context.root);
+		if (!matches) diagnostic(context, "INDEX_STALE", "warning", context.paths.index, "Derived search index is stale or has a hash mismatch.");
+	} catch (cause) {
+		if (cause instanceof LlmWikiError && cause.code === "ABORTED") throw cause;
+		throwIfAborted(context.signal);
+		const nestedCode = cause instanceof Error && cause.cause !== void 0 ? cause.cause.code : void 0;
+		if (!(cause instanceof LlmWikiError && (cause.code === "INVALID_PAGE" || cause.code === "INVALID_PATH" || cause.code === "UNSAFE_FILESYSTEM" && (cause.cause === void 0 || nestedCode === "ENOENT" || nestedCode === "ENOTDIR")))) throw cause;
+		diagnostic(context, "INDEX_STALE", "warning", context.paths.index, "Derived search index is stale or has a hash mismatch.");
+	}
+}
+function lintRootFailure(paths, cause) {
+	const components = paths.authority.root.split("/").filter(Boolean);
+	if (!(cause instanceof WikiTraversalError) || cause.segments.length !== components.length || !cause.segments.every((segment, index) => segment === components[index]) || cause.entryKind === "unknown") throw cause;
+	const symlink = cause.entryKind === "symlink";
+	return {
+		diagnostics: [{
+			code: symlink ? "UNSAFE_SYMLINK" : "ROOT_NOT_DIRECTORY",
+			severity: "error",
+			path: ".",
+			message: symlink ? "Wiki root must not be a symbolic link." : "Wiki root is not a directory."
+		}],
+		errorCount: 1,
+		warningCount: 0,
+		filesExamined: 0
+	};
+}
+async function lintWiki(paths, signal, root) {
+	throwIfAborted(signal);
+	if (root === void 0) try {
+		return await withWikiRoot(paths.authority, { signal }, (held) => lintWiki(paths, signal, held)) ?? lintWiki(paths, signal, null);
+	} catch (cause) {
+		throwIfAborted(signal);
+		return lintRootFailure(paths, cause);
+	}
+	if (root === null) return {
+		diagnostics: [{
+			code: "ROOT_MISSING",
+			severity: "error",
+			path: ".",
+			message: "Wiki root is missing."
+		}],
+		errorCount: 1,
+		warningCount: 0,
+		filesExamined: 0
+	};
+	const context = {
+		paths,
+		root,
+		signal,
+		diagnostics: [],
+		examinedPaths: /* @__PURE__ */ new Set()
+	};
+	{
+		await scanTempsAndSymlinks(paths.root, context);
+		const schemaStat = await stat(paths.schema, context);
+		if (schemaStat === null) diagnostic(context, "SCHEMA_MISSING", "error", paths.schema, "Wiki schema is missing.");
+		else if (schemaStat.isSymbolicLink()) {} else if (!schemaStat.isFile()) diagnostic(context, "REQUIRED_PATH_NOT_DIRECTORY", "error", paths.schema, "Wiki schema must be a regular file.");
+		else {
+			const bytes = await readBytes$1(paths.schema, context);
+			if (bytes !== null) try {
+				decodeUtf8(bytes);
+			} catch {
+				diagnostic(context, "INVALID_UTF8", "error", paths.schema, "Wiki schema is not valid UTF-8.");
+			}
+		}
+		const sources = await inspectSources(context);
+		const referencedSources = await inspectPages(sources, context);
+		for (const id of sources) if (!referencedSources.has(id)) diagnostic(context, "SOURCE_UNREFERENCED", "warning", paths.sourceMetadata(sourceId(id)), "Source is not referenced by any valid page.");
+		await inspectIndex(context);
+	}
+	throwIfAborted(signal);
+	context.diagnostics.sort((left, right) => compareCodeUnits$1(left.path, right.path) || (left.line ?? Number.POSITIVE_INFINITY) - (right.line ?? Number.POSITIVE_INFINITY) || compareCodeUnits$1(left.code, right.code) || compareCodeUnits$1(left.message, right.message));
+	return {
+		diagnostics: context.diagnostics,
+		errorCount: context.diagnostics.filter(({ severity }) => severity === "error").length,
+		warningCount: context.diagnostics.filter(({ severity }) => severity === "warning").length,
+		filesExamined: context.examinedPaths.size
+	};
+}
+//#endregion
+//#region src/service.ts
+const DEFAULT_SCHEMA = `# LLM Wiki Schema
+
+This schema is human-owned organization and workflow guidance. The plugin creates it only when absent, exposes it through status, and never rewrites it; system and user instructions take precedence. There is no schema mutation API; schema evolution remains intentionally unresolved pending authorization/confirmation, visible audit evidence, and optimistic-concurrency/lost-update product decisions.
+
+Pages are durable source-linked Markdown notes. Keep titles and summaries concise, organize related claims under headings, maintain useful page links, preserve material disagreements and dated supersessions, and cite every relevant existing immutable source ID in frontmatter. Source citation proves record existence, not claim-level support.
+
+Evidence maintenance: call llmwiki_status first and read schemaText when non-null. On a fresh root, status returns schemaText null without creating storage; supplied material alone is not authorization to preserve it. Only with explicit authorization to preserve the source, call llmwiki_add_source to initialize storage, then call status again and read the schema before classification or page maintenance. List sources and pages, then search and read relevant records before writing. Only with explicit authorization to preserve candidate material, add it if the fresh-root branch did not, then classify its effect as new, update, contradiction, or no material change. Separately, only when the user request authorizes maintenance, update every materially affected page, preserve disagreements and links, and cite existing source IDs. Run llmwiki_lint unconditionally before any semantic-review pass, including read-only, no-write, and no-material-change cases; it is structural only and never repairs artifacts or makes semantic judgments. After any authorized durable updates, rerun structural lint.
+
+Page writes require expectedSha256: null for a new page, or the exact current raw-byte sha256 from llmwiki_read_page or llmwiki_list_pages for an update. On PAGE_CONFLICT, reread the winning page and reconcile before any further authorized write; never automatically retry or overwrite blindly. This concurrency protection is limited to one service activation, not cross-process writers.
+
+Semantic review (separate from structural lint): only after the unconditional structural lint, list pages and sources. Select and state the review scope, compare dated and qualified claims across every scoped page, every source it cites, and every new candidate source relevant to that scope, and report classified contradiction, superseded, unsupported, and missing-link findings with visible page and source IDs. These semantic findings are agent judgments, never llmwiki_lint diagnostics. Only when the user request authorizes maintenance, update affected pages while preserving disagreements or dated supersessions and maintain links; after any such durable updates, rerun structural lint.
+`;
+const HASH = /^[0-9a-f]{64}$/u;
+const NON_WHITESPACE = /\S/u;
+const INCOMPLETE_UTF8_RANGE = "Source byte range contains no complete UTF-8 code point; increase the limit.";
+const CURSOR_TEXT = /^[A-Za-z0-9_-]+$/u;
+function compareCodeUnits(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+function catalogCorrupt(message) {
+	return new LlmWikiError("CATALOG_CORRUPT", message);
+}
+function invalidCursor() {
+	throw new LlmWikiError("INVALID_CURSOR", "Catalog cursor is invalid.");
+}
+function encodeCursor(kind, after) {
+	return Buffer.from(JSON.stringify({
+		v: 1,
+		kind,
+		after
+	}), "utf8").toString("base64url");
+}
+function decodeCursor(cursor, kind) {
+	if (cursor === void 0) return void 0;
+	if (!CURSOR_TEXT.test(cursor) || cursor.includes("=")) return invalidCursor();
+	let text;
+	try {
+		const bytes = Buffer.from(cursor, "base64url");
+		if (bytes.toString("base64url") !== cursor) return invalidCursor();
+		text = decodeUtf8(bytes);
+	} catch {
+		return invalidCursor();
+	}
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return invalidCursor();
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return invalidCursor();
+	const object = value;
+	if (object.v !== 1 || object.kind !== kind || typeof object.after !== "string" || (kind === "sources" ? !isSourceId(object.after) : !isPageId(object.after)) || JSON.stringify({
+		v: 1,
+		kind,
+		after: object.after
+	}) !== text) return invalidCursor();
+	return object.after;
+}
+function catalogLimit(request, maximum) {
+	const value = request.limit ?? maximum;
+	if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw limit("Catalog limit is outside the configured range.");
+	return value;
+}
+function appendCatalogItem(items, id, after, limitValue, create) {
+	if (after !== void 0 && compareCodeUnits(id, after) <= 0) return false;
+	if (items.length === limitValue) return true;
+	items.push(create());
+	return false;
+}
+function finishCatalogPage(kind, items, hasMore) {
+	return {
+		items,
+		nextCursor: hasMore ? encodeCursor(kind, items[items.length - 1].id) : null
+	};
+}
+function unsafe() {
+	throw new LlmWikiError("UNSAFE_FILESYSTEM", "The wiki filesystem changed or contains an unsafe entry.");
+}
+async function inDirectory(paths, path, signal, work) {
+	if (paths.rootDirectory === null) return null;
+	return paths.rootDirectory.directory(wikiRelativeSegments(paths, path), { signal }, work);
+}
+async function inspectPath(paths, path, signal) {
+	const segments = wikiRelativeSegments(paths, path);
+	const name = segments.at(-1);
+	return inDirectory(paths, join(paths.root, ...segments.slice(0, -1)), signal, (directory) => directory.inspect(name, signal));
+}
+async function readBytes(paths, path, signal) {
+	const segments = wikiRelativeSegments(paths, path);
+	return inDirectory(paths, join(paths.root, ...segments.slice(0, -1)), signal, async (directory) => (await directory.read(segments.at(-1), signal))?.bytes ?? null);
+}
+async function collectCatalogPageFiles(directory, paths, output, snapshots, signal) {
+	const pending = [{
+		path: directory,
+		logicalPath: ""
+	}];
+	while (pending.length > 0) {
+		throwIfAborted(signal);
+		const current = pending.pop();
+		const read = await readSafeCatalogDirectory(current.path, paths, signal);
+		snapshots.push(read.snapshot);
+		for (const entry of read.entries) {
+			const logicalPath = current.logicalPath === "" ? entry.name : `${current.logicalPath}/${entry.name}`;
+			const child = join(current.path, entry.name);
+			if (entry.isSymbolicLink()) unsafe();
+			if (entry.isDirectory()) pending.push({
+				path: child,
+				logicalPath
+			});
+			else if (entry.isFile()) {
+				const snapshot = await snapshotSafeCatalogFile(child, paths, signal);
+				snapshots.push(snapshot);
+				output.push({
+					path: child,
+					logicalPath,
+					snapshot
+				});
+			} else unsafe();
+		}
+	}
+}
+const EMPTY_INDEX_STATUS = Object.freeze({
+	present: false,
+	fresh: false,
+	formatVersion: null,
+	sectionCount: 0
+});
+function hash(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+function canonicalJson(value) {
+	return encodeUtf8(`${JSON.stringify(value, null, 2)}\n`);
+}
+function sameStableSnapshot(before, after) {
+	return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs;
+}
+async function revalidateCatalogSnapshot(snapshot, paths, signal) {
+	try {
+		const current = snapshot.kind === "file" ? await snapshotSafeCatalogFile(snapshot.path, paths, signal) : (await readSafeCatalogDirectory(snapshot.path, paths, signal)).snapshot;
+		if (!sameStableSnapshot(snapshot.stats, current.stats)) unsafe();
+		if (snapshot.children !== void 0 && (current.children?.length !== snapshot.children.length || current.children.some((child, index) => child !== snapshot.children[index]))) unsafe();
+	} catch (cause) {
+		throwIfAborted(signal);
+		if (cause instanceof LlmWikiError) throw cause;
+		throw new LlmWikiError("UNSAFE_FILESYSTEM", "Unable to revalidate the catalog safely.", { cause });
+	}
+}
+async function readSafeCatalogDirectory(path, paths, signal) {
+	const before = await inspectPath(paths, path, signal);
+	if (before === null || !before.isDirectory() || before.isSymbolicLink()) unsafe();
+	const listed = await inDirectory(paths, path, signal, (directory) => directory.list(signal));
+	if (listed === null) unsafe();
+	const final = await inspectPath(paths, path, signal);
+	if (final === null || !sameStableSnapshot(before, final)) unsafe();
+	const entries = listed.map((entry) => ({
+		name: entry.name,
+		isFile: () => entry.stat.isFile(),
+		isDirectory: () => entry.stat.isDirectory(),
+		isSymbolicLink: () => entry.stat.isSymbolicLink()
+	}));
+	return {
+		entries,
+		snapshot: {
+			path,
+			stats: final,
+			kind: "directory",
+			children: entries.map((entry) => `${entry.name}\0${entry.isFile() ? "file" : entry.isDirectory() ? "directory" : entry.isSymbolicLink() ? "symlink" : "other"}`).sort(compareCodeUnits)
+		}
+	};
+}
+async function snapshotSafeCatalogFile(path, paths, signal) {
+	const stats = await inspectPath(paths, path, signal);
+	if (stats === null || !stats.isFile() || stats.isSymbolicLink()) unsafe();
+	return {
+		path,
+		stats,
+		kind: "file"
+	};
+}
+async function readSafeCatalogFile(path, paths, signal) {
+	const segments = wikiRelativeSegments(paths, path);
+	const read = await inDirectory(paths, join(paths.root, ...segments.slice(0, -1)), signal, (directory) => directory.read(segments.at(-1), signal));
+	if (read === null) throw Object.assign(/* @__PURE__ */ new Error("Wiki file is missing."), { code: "ENOENT" });
+	return {
+		bytes: read.bytes,
+		snapshot: {
+			path,
+			stats: read.snapshot.stat,
+			kind: "file"
+		}
+	};
+}
+function missing(code, message) {
+	return new LlmWikiError(code, message);
+}
+function limit(message) {
+	return new LlmWikiError("LIMIT_EXCEEDED", message);
+}
+function isMissing(cause) {
+	return cause.code === "ENOENT";
+}
+function sanitizeFailure(cause) {
+	if (cause instanceof LlmWikiError) throw cause.cause === void 0 ? cause : new LlmWikiError(cause.code, cause.message);
+	if (typeof cause.code === "string") throw new LlmWikiError("UNSAFE_FILESYSTEM", "The wiki filesystem operation failed.");
+	throw cause;
+}
+function validateText(value, field) {
+	if (!NON_WHITESPACE.test(value)) throw new LlmWikiError("INVALID_PAGE", `${field} must not be empty.`);
+}
+function parseMetadata(bytes, expectedId) {
+	let value;
+	try {
+		value = JSON.parse(decodeUtf8(bytes));
+	} catch (cause) {
+		throw new LlmWikiError("INVALID_PAGE", "Source metadata is malformed.", { cause });
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new LlmWikiError("INVALID_PAGE", "Source metadata is malformed.");
+	const object = value;
+	const keys = Object.keys(object);
+	const expectedKeys = object.origin === void 0 ? [
+		"id",
+		"name",
+		"mediaType",
+		"byteCount",
+		"capturedAt"
+	] : [
+		"id",
+		"name",
+		"mediaType",
+		"byteCount",
+		"capturedAt",
+		"origin"
+	];
+	if (keys.length !== expectedKeys.length || keys.some((key, index) => key !== expectedKeys[index]) || object.id !== expectedId || typeof object.name !== "string" || !NON_WHITESPACE.test(object.name) || typeof object.mediaType !== "string" || !NON_WHITESPACE.test(object.mediaType) || typeof object.byteCount !== "number" || !Number.isSafeInteger(object.byteCount) || object.byteCount < 0 || typeof object.capturedAt !== "string" || Number.isNaN(Date.parse(object.capturedAt)) || new Date(object.capturedAt).toISOString() !== object.capturedAt || object.origin !== void 0 && (typeof object.origin !== "string" || !NON_WHITESPACE.test(object.origin)) || !Buffer.from(canonicalJson(object)).equals(Buffer.from(bytes))) throw new LlmWikiError("INVALID_PAGE", "Source metadata does not match its required schema.");
+	return object;
+}
+function alignedRange(bytes, offset, limitValue) {
+	let start = offset;
+	while (start < bytes.byteLength && (bytes[start] & 192) === 128) start += 1;
+	let end = Math.max(start, Math.min(bytes.byteLength, offset + limitValue));
+	while (end > start && end < bytes.byteLength && (bytes[end] & 192) === 128) end -= 1;
+	return {
+		start,
+		end
+	};
+}
+async function regularFile(path, paths, signal) {
+	const stat = await inspectPath(paths, path, signal);
+	if (stat === null) return false;
+	if (!stat.isFile() || stat.isSymbolicLink()) unsafe();
+	return true;
+}
+async function regularDirectory(path, paths, signal) {
+	const stat = await inspectPath(paths, path, signal);
+	if (stat === null) return false;
+	if (!stat.isDirectory() || stat.isSymbolicLink()) unsafe();
+	return true;
+}
+function wikiRootPresent(paths, signal) {
+	throwIfAborted(signal);
+	return paths.rootDirectory !== null;
+}
+async function countFiles(directory, suffix, paths, signal) {
+	let total = 0;
+	const pending = [directory];
+	while (pending.length > 0) {
+		const current = pending.pop();
+		const entries = await inDirectory(paths, current, signal, (capability) => capability.list(signal));
+		if (entries === null) unsafe();
+		for (const entry of entries) {
+			throwIfAborted(signal);
+			if (entry.stat.isSymbolicLink()) unsafe();
+			if (entry.stat.isDirectory()) {
+				if (suffix !== void 0 && entry.name.endsWith(suffix)) unsafe();
+				pending.push(join(current, entry.name));
+			} else if (!entry.stat.isFile()) unsafe();
+			else if (suffix === void 0 || entry.name.endsWith(suffix)) total += 1;
+		}
+	}
+	return total;
+}
+async function countSources(paths, signal) {
+	const entries = await inDirectory(paths, paths.sources, signal, (directory) => directory.list(signal));
+	if (entries === null) unsafe();
+	let total = 0;
+	for (const entry of entries) {
+		if (entry.stat.isSymbolicLink() || !entry.stat.isDirectory()) unsafe();
+		const directory = join(paths.sources, entry.name);
+		await countFiles(directory, void 0, paths, signal);
+		if (HASH.test(entry.name)) {
+			if (!await regularFile(join(directory, "content"), paths, signal) || !await regularFile(join(directory, "metadata.json"), paths, signal)) unsafe();
+			total += 1;
+		}
+	}
+	return total;
+}
+const configKey = Symbol("llmwiki.config");
+var LlmWikiService = class extends Service {
+	static Config = Config;
+	[configKey];
+	pathsValue;
+	queue = Promise.resolve();
+	queued = /* @__PURE__ */ new Set();
+	disposed = false;
+	constructor(ctx, config = {}) {
+		super(ctx, "llmwiki");
+		const resolved = resolveConfig(config);
+		this[configKey] = Object.freeze({
+			...resolved,
+			root: resolve(process.cwd(), resolved.root)
+		});
+		ctx.effect(() => () => {
+			this.disposed = true;
+			const error = new LlmWikiError("NOT_INITIALIZED", "The llmwiki service has been disposed.");
+			for (const reject of this.queued) reject(error);
+			this.queued.clear();
+			return this.queue.catch(() => void 0);
+		}, "llmwiki.service");
+	}
+	enqueue(work, signal, initialize = true) {
+		if (this.disposed) return Promise.reject(new LlmWikiError("NOT_INITIALIZED", "The llmwiki service has been disposed."));
+		let started = false;
+		let settled = false;
+		let cancelled = false;
+		let resolveResult;
+		let rejectResult;
+		const result = new Promise((resolvePromise, rejectPromise) => {
+			resolveResult = resolvePromise;
+			rejectResult = rejectPromise;
+		});
+		result.catch(() => void 0);
+		const rejectQueued = (error) => {
+			if (started || settled) return;
+			cancelled = true;
+			settled = true;
+			rejectResult(error);
+		};
+		const onAbort = () => rejectQueued(new LlmWikiError("ABORTED", "The operation was aborted."));
+		this.queued.add(rejectQueued);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		if (signal?.aborted) onAbort();
+		const scheduled = this.queue.then(async () => {
+			started = true;
+			this.queued.delete(rejectQueued);
+			if (cancelled) return;
+			try {
+				if (this.disposed) throw new LlmWikiError("NOT_INITIALIZED", "The llmwiki service has been disposed.");
+				const paths = this.pathsValue ?? createWikiPaths(this[configKey].root);
+				let ran = false;
+				const pinned = await withWikiRoot(paths.authority, {
+					create: initialize,
+					signal
+				}, async (rootDirectory) => {
+					ran = true;
+					const operationPaths = {
+						...paths,
+						rootDirectory
+					};
+					if (initialize) await this.initialize(operationPaths, signal);
+					throwIfAborted(signal);
+					return work(operationPaths);
+				});
+				const value = ran ? pinned : await work({
+					...paths,
+					rootDirectory: null
+				});
+				if (!settled) {
+					settled = true;
+					resolveResult(value);
+				}
+			} catch (cause) {
+				if (!settled) {
+					settled = true;
+					try {
+						sanitizeFailure(cause);
+					} catch (error) {
+						rejectResult(error);
+					}
+				}
+			} finally {
+				signal?.removeEventListener("abort", onAbort);
+			}
+		});
+		this.queue = scheduled.then(() => void 0, () => void 0);
+		return result;
+	}
+	async initialize(paths, signal) {
+		if (this.pathsValue !== void 0) return;
+		const root = paths.rootDirectory;
+		for (const name of [
+			"sources",
+			"pages",
+			".index"
+		]) if (await root.directory([name], {
+			create: true,
+			signal
+		}, () => Promise.resolve(true)) === null) unsafe();
+		if (!await regularFile(paths.schema, paths, signal)) try {
+			await root.createFileExclusive("schema.md", encodeUtf8(DEFAULT_SCHEMA), {
+				mode: 384,
+				signal
+			});
+		} catch (cause) {
+			throwIfAborted(signal);
+			if (cause.code !== "EEXIST") throw cause;
+		}
+		if (await root.read("schema.md", signal) === null) unsafe();
+		paths.authority.identity = await root.identity();
+		this.pathsValue = createWikiPaths(paths.root, paths.authority);
+	}
+	async status(signal) {
+		return this.enqueue(async (paths) => {
+			if (!wikiRootPresent(paths, signal)) return {
+				initialized: false,
+				sourceCount: 0,
+				pageCount: 0,
+				schemaText: null,
+				index: EMPTY_INDEX_STATUS
+			};
+			const [schemaPresent, sourcesPresent, pagesPresent, indexPresent] = await allSettledOnFailure([
+				regularFile(paths.schema, paths, signal),
+				regularDirectory(paths.sources, paths, signal),
+				regularDirectory(paths.pages, paths, signal),
+				regularDirectory(paths.index, paths, signal)
+			]);
+			const [schemaBytes, sourceCount, pageCount, index] = await allSettledOnFailure([
+				schemaPresent ? readBytes(paths, paths.schema, signal) : null,
+				sourcesPresent ? countSources(paths, signal) : 0,
+				pagesPresent ? countFiles(paths.pages, ".md", paths, signal) : 0,
+				indexPresent ? this.indexStatus(paths, signal) : EMPTY_INDEX_STATUS
+			]);
+			throwIfAborted(signal);
+			return {
+				initialized: schemaPresent && sourcesPresent && pagesPresent && indexPresent,
+				sourceCount,
+				pageCount,
+				schemaText: schemaBytes === null ? null : decodeUtf8(schemaBytes),
+				index
+			};
+		}, signal, false);
+	}
+	async addSource(input, signal) {
+		if (this.disposed) return Promise.reject(new LlmWikiError("NOT_INITIALIZED", "The llmwiki service has been disposed."));
+		throwIfAborted(signal);
+		validateText(input.name, "Source name");
+		const mediaType = input.mediaType ?? "text/plain; charset=utf-8";
+		validateText(mediaType, "Source media type");
+		if (input.origin !== void 0) validateText(input.origin, "Source origin");
+		if (input.content.length === 0) throw new LlmWikiError("INVALID_PAGE", "Source content must not be empty.");
+		const content = encodeUtf8(input.content);
+		if (content.byteLength > this[configKey].maxSourceBytes) throw limit("Source content exceeds maxSourceBytes.");
+		const id = sourceId(hash(content));
+		return this.enqueue(async (paths) => {
+			const result = await paths.rootDirectory.directory(["sources"], { signal }, async (sources) => {
+				const allocation = await sources.createDirectory(id, signal);
+				try {
+					const result = await sources.directory([id], { signal }, async (directory) => {
+						const identity = await directory.identity();
+						if (identity.dev !== allocation.identity.dev || identity.ino !== allocation.identity.ino) unsafe();
+						const children = await directory.list(signal);
+						if (children.some((child) => child.name === "metadata.json")) {
+							const existing = await this.readSourceRecord(paths, id, signal);
+							if (children.length !== 2 || children[0]?.name !== "content" || children[1]?.name !== "metadata.json") unsafe();
+							for (const child of children) if (!child.stat.isFile() || !await directory.validate(child, signal)) unsafe();
+							for (const snapshot of existing.snapshots) await revalidateCatalogSnapshot(snapshot, paths, signal);
+							throwIfAborted(signal);
+							return {
+								id,
+								deduplicated: true,
+								metadata: existing.metadata
+							};
+						}
+						let contentPresent = false;
+						for (const child of children) {
+							if (!child.stat.isFile() || child.name !== "content" && !isAtomicTemporaryName(child.name, "content") && !isAtomicTemporaryName(child.name, "metadata.json")) unsafe();
+							if (child.name === "content") {
+								if (child.stat.size !== BigInt(content.byteLength)) throw new LlmWikiError("INVALID_PAGE", "Source record content does not match its immutable identity.");
+								const read = await directory.read(child.name, signal);
+								if (!read || !sameFileSnapshot(child.stat, read.snapshot.stat)) unsafe();
+								if (hash(read.bytes) !== id || !read.bytes.equals(content)) throw new LlmWikiError("INVALID_PAGE", "Source record content does not match its immutable identity.");
+								contentPresent = true;
+							}
+						}
+						const currentChildren = await directory.list(signal);
+						if (currentChildren.length !== children.length || currentChildren.some((child, index) => {
+							const previous = children[index];
+							return child.name !== previous?.name || !sameFileSnapshot(child.stat, previous.stat);
+						})) unsafe();
+						for (const child of children) if (!await directory.validate(child, signal)) unsafe();
+						throwIfAborted(signal);
+						for (const child of children) if (child.name !== "content") {
+							throwIfAborted(signal);
+							await directory.unlink(child.name, child.stat);
+						}
+						const metadata = {
+							id,
+							name: input.name,
+							mediaType,
+							byteCount: content.byteLength,
+							capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+							...input.origin === void 0 ? {} : { origin: input.origin }
+						};
+						let ownedContent;
+						try {
+							if (!contentPresent) {
+								await atomicWriteFile(directory, "content", content, { signal });
+								const written = await directory.read("content", signal);
+								if (!written?.bytes.equals(content)) unsafe();
+								ownedContent = written.snapshot;
+							}
+							throwIfAborted(signal);
+							await atomicWriteFile(directory, "metadata.json", canonicalJson(metadata), { signal });
+							return {
+								id,
+								deduplicated: false,
+								metadata
+							};
+						} catch (cause) {
+							if (ownedContent) await directory.unlink("content", ownedContent.stat).catch(() => void 0);
+							throw cause;
+						}
+					});
+					if (result === null) unsafe();
+					return result;
+				} catch (cause) {
+					if (allocation.created) await sources.removeCreatedSource(id, allocation.identity, []).catch(() => void 0);
+					throw cause;
+				}
+			});
+			if (result === null) unsafe();
+			return result;
+		}, signal);
+	}
+	async readSource(id, range, signal) {
+		sourceId(id);
+		return this.enqueue(async (paths) => {
+			const record = await this.readSourceRecord(paths, id, signal);
+			const offset = range?.offset ?? 0;
+			const limitValue = range?.limit ?? this[configKey].maxSourceBytes;
+			if (!Number.isSafeInteger(offset) || offset < 0 || offset > record.content.byteLength) throw limit("Source byte offset is outside the source.");
+			if (!Number.isSafeInteger(limitValue) || limitValue < 1 || limitValue > this[configKey].maxSourceBytes) throw limit("Source byte limit is outside the configured range.");
+			const { start, end } = alignedRange(record.content, offset, limitValue);
+			if (offset < record.content.byteLength && end === start) throw limit(INCOMPLETE_UTF8_RANGE);
+			return {
+				id,
+				content: decodeUtf8(record.content.subarray(start, end)),
+				metadata: record.metadata,
+				byteStart: start,
+				byteEnd: end,
+				byteCount: record.content.byteLength
+			};
+		}, signal);
+	}
+	async listSources(request = {}, signal) {
+		throwIfAborted(signal);
+		const limitValue = catalogLimit(request, this[configKey].maxResults);
+		const after = decodeCursor(request.cursor, "sources");
+		return this.enqueue(async (paths) => {
+			if (!wikiRootPresent(paths, signal) || !await regularDirectory(paths.sources, paths, signal)) return {
+				items: [],
+				nextCursor: null
+			};
+			const items = [];
+			const snapshots = [];
+			let hasMore = false;
+			const root = await readSafeCatalogDirectory(paths.sources, paths, signal);
+			throwIfAborted(signal);
+			snapshots.push(root.snapshot);
+			const discovered = root.entries.sort((a, b) => compareCodeUnits(a.name, b.name));
+			for (const entry of discovered) {
+				throwIfAborted(signal);
+				if (entry.isSymbolicLink()) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Symbolic links are not allowed in the wiki.");
+				if (!entry.isDirectory()) throw new LlmWikiError("UNSAFE_FILESYSTEM", "The sources tree may contain only regular source directories.");
+				if (!isSourceId(entry.name)) throw catalogCorrupt("The source catalog contains an invalid record.");
+				const id = sourceId(entry.name);
+				const recordPath = join(paths.sources, entry.name);
+				const recordDirectory = await readSafeCatalogDirectory(recordPath, paths, signal);
+				throwIfAborted(signal);
+				snapshots.push(recordDirectory.snapshot);
+				const children = recordDirectory.entries.sort((a, b) => compareCodeUnits(a.name, b.name));
+				for (const child of children) {
+					throwIfAborted(signal);
+					if (child.isSymbolicLink() || !child.isFile()) throw new LlmWikiError("UNSAFE_FILESYSTEM", "Source records must contain only regular files.");
+				}
+				if (children.length !== 2 || children[0]?.name !== "content" || children[1]?.name !== "metadata.json") throw catalogCorrupt("The source catalog contains an invalid record.");
+				const contentSnapshot = await snapshotSafeCatalogFile(join(recordPath, "content"), paths, signal);
+				throwIfAborted(signal);
+				const metadataSnapshot = await snapshotSafeCatalogFile(join(recordPath, "metadata.json"), paths, signal);
+				throwIfAborted(signal);
+				snapshots.push(contentSnapshot, metadataSnapshot);
+				try {
+					const record = await this.readSourceRecord(paths, id, signal);
+					throwIfAborted(signal);
+					hasMore ||= appendCatalogItem(items, record.metadata.id, after, limitValue, () => ({
+						id: record.metadata.id,
+						name: record.metadata.name,
+						mediaType: record.metadata.mediaType,
+						byteCount: record.metadata.byteCount,
+						capturedAt: record.metadata.capturedAt,
+						...record.metadata.origin === void 0 ? {} : { origin: record.metadata.origin }
+					}));
+				} catch (cause) {
+					if (cause instanceof LlmWikiError && (cause.code === "ABORTED" || cause.code === "UNSAFE_FILESYSTEM")) throw cause;
+					if (!isMissing(cause) && typeof cause.code === "string" && !(cause instanceof LlmWikiError)) throw cause;
+					await revalidateCatalogSnapshot(recordDirectory.snapshot, paths, signal);
+					throwIfAborted(signal);
+					await revalidateCatalogSnapshot(contentSnapshot, paths, signal);
+					throwIfAborted(signal);
+					await revalidateCatalogSnapshot(metadataSnapshot, paths, signal);
+					throwIfAborted(signal);
+					throw catalogCorrupt("The source catalog contains an invalid record.");
+				}
+			}
+			for (const snapshot of snapshots) {
+				throwIfAborted(signal);
+				await revalidateCatalogSnapshot(snapshot, paths, signal);
+				throwIfAborted(signal);
+			}
+			return finishCatalogPage("sources", items, hasMore);
+		}, signal, false);
+	}
+	async listPages(request = {}, signal) {
+		throwIfAborted(signal);
+		const limitValue = catalogLimit(request, this[configKey].maxResults);
+		const after = decodeCursor(request.cursor, "pages");
+		return this.enqueue(async (paths) => {
+			if (!wikiRootPresent(paths, signal) || !await regularDirectory(paths.pages, paths, signal)) return {
+				items: [],
+				nextCursor: null
+			};
+			const files = [];
+			const snapshots = [];
+			await collectCatalogPageFiles(paths.pages, paths, files, snapshots, signal);
+			throwIfAborted(signal);
+			files.sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath));
+			const items = [];
+			let hasMore = false;
+			for (const file of files) {
+				throwIfAborted(signal);
+				const logical = file.logicalPath;
+				if (!logical.endsWith(".md") || !isPageId(logical.slice(0, -3))) {
+					for (const snapshot of snapshots) {
+						throwIfAborted(signal);
+						await revalidateCatalogSnapshot(snapshot, paths, signal);
+						throwIfAborted(signal);
+					}
+					throw catalogCorrupt("The page catalog contains an invalid record.");
+				}
+				try {
+					const read = await readSafeCatalogFile(file.path, paths, signal);
+					throwIfAborted(signal);
+					if (!sameStableSnapshot(file.snapshot.stats, read.snapshot.stats)) throw new LlmWikiError("UNSAFE_FILESYSTEM", "The catalog changed while it was being read.");
+					const parsed = parsePageMarkdown(decodeUtf8(read.bytes));
+					const id = pageId(logical.slice(0, -3));
+					hasMore ||= appendCatalogItem(items, id, after, limitValue, () => ({
+						id,
+						title: parsed.metadata.title,
+						summary: parsed.metadata.summary,
+						sources: [...parsed.metadata.sources],
+						byteCount: read.bytes.byteLength,
+						sha256: hash(read.bytes)
+					}));
+				} catch (cause) {
+					if (cause instanceof LlmWikiError && (cause.code === "ABORTED" || cause.code === "UNSAFE_FILESYSTEM")) throw cause;
+					if (!isMissing(cause) && typeof cause.code === "string" && !(cause instanceof LlmWikiError)) throw cause;
+					await revalidateCatalogSnapshot(file.snapshot, paths, signal);
+					throwIfAborted(signal);
+					throw catalogCorrupt("The page catalog contains an invalid record.");
+				}
+			}
+			for (const snapshot of snapshots) {
+				throwIfAborted(signal);
+				await revalidateCatalogSnapshot(snapshot, paths, signal);
+				throwIfAborted(signal);
+			}
+			return finishCatalogPage("pages", items, hasMore);
+		}, signal, false);
+	}
+	async readSourceRecord(paths, id, signal) {
+		try {
+			const contentPath = paths.sourceContent(id);
+			const metadataPath = paths.sourceMetadata(id);
+			const contentPresent = await regularFile(contentPath, paths, signal);
+			throwIfAborted(signal);
+			const metadataPresent = await regularFile(metadataPath, paths, signal);
+			throwIfAborted(signal);
+			if (!contentPresent || !metadataPresent) throw missing("SOURCE_NOT_FOUND", "Source was not found.");
+			const metadataRead = await readSafeCatalogFile(metadataPath, paths, signal);
+			throwIfAborted(signal);
+			const metadata = parseMetadata(metadataRead.bytes, id);
+			const contentRead = await readSafeCatalogFile(contentPath, paths, signal);
+			throwIfAborted(signal);
+			const snapshots = [metadataRead.snapshot, contentRead.snapshot];
+			try {
+				if (hash(contentRead.bytes) !== id || metadata.byteCount !== contentRead.bytes.byteLength) throw new LlmWikiError("INVALID_PAGE", "Source record content does not match its immutable identity.");
+				decodeUtf8(contentRead.bytes);
+				return {
+					content: contentRead.bytes,
+					metadata,
+					snapshots
+				};
+			} catch (cause) {
+				for (const snapshot of snapshots) {
+					throwIfAborted(signal);
+					await revalidateCatalogSnapshot(snapshot, paths, signal);
+					throwIfAborted(signal);
+				}
+				throw cause;
+			}
+		} catch (cause) {
+			throwIfAborted(signal);
+			if (isMissing(cause)) throw missing("SOURCE_NOT_FOUND", "Source was not found.");
+			throw cause;
+		}
+	}
+	async readPage(id, signal) {
+		pageId(id);
+		return this.enqueue(async (paths) => {
+			try {
+				const target = paths.page(id);
+				if (!await regularFile(target, paths, signal)) throw missing("PAGE_NOT_FOUND", "Page was not found.");
+				const bytes = await readBytes(paths, target, signal);
+				if (bytes === null) throw missing("PAGE_NOT_FOUND", "Page was not found.");
+				throwIfAborted(signal);
+				const markdown = decodeUtf8(bytes);
+				return {
+					id,
+					markdown,
+					metadata: parsePageMarkdown(markdown).metadata,
+					sha256: hash(bytes)
+				};
+			} catch (cause) {
+				throwIfAborted(signal);
+				if (isMissing(cause)) throw missing("PAGE_NOT_FOUND", "Page was not found.");
+				throw cause;
+			}
+		}, signal);
+	}
+	async upsertPage(input, signal) {
+		if (this.disposed) return Promise.reject(new LlmWikiError("NOT_INITIALIZED", "The llmwiki service has been disposed."));
+		throwIfAborted(signal);
+		const expectedSha256 = input.expectedSha256;
+		if (expectedSha256 !== null && (typeof expectedSha256 !== "string" || !HASH.test(expectedSha256))) throw new LlmWikiError("INVALID_PRECONDITION", "expectedSha256 must be null or a 64-character lowercase hexadecimal SHA-256 hash.");
+		pageId(input.id);
+		return this.enqueue(async (paths) => {
+			const bytes = encodeUtf8(renderPageMarkdown(input, input.body));
+			if (bytes.byteLength > this[configKey].maxPageBytes) throw limit("Page content exceeds maxPageBytes.");
+			for (const id of input.sources) await this.readSourceRecord(paths, id, signal);
+			const segments = wikiRelativeSegments(paths, paths.page(input.id));
+			const receipt = await paths.rootDirectory.directory(segments.slice(0, -1), {
+				create: expectedSha256 === null,
+				signal
+			}, async (directory) => {
+				for (const id of input.sources) await this.readSourceRecord(paths, id, signal);
+				const existing = await directory.read(segments.at(-1), signal);
+				if (expectedSha256 === null ? existing !== null : existing === null || hash(existing.bytes) !== expectedSha256) throw new LlmWikiError("PAGE_CONFLICT", "Page does not match expectedSha256; reread and reconcile before writing.");
+				await atomicWriteFile(directory, segments.at(-1), bytes, { signal });
+				return {
+					id: input.id,
+					created: existing === null,
+					sha256: hash(bytes)
+				};
+			});
+			if (receipt === null) {
+				if (expectedSha256 !== null) throw new LlmWikiError("PAGE_CONFLICT", "Page does not match expectedSha256; reread and reconcile before writing.");
+				unsafe();
+			}
+			return receipt;
+		}, signal);
+	}
+	async lint(signal) {
+		return this.enqueue((paths) => lintWiki(paths, signal, paths.rootDirectory), signal, false);
+	}
+	async search(query, limitValue = this[configKey].maxResults, signal) {
+		throwIfAborted(signal);
+		if (!Number.isSafeInteger(limitValue) || limitValue < 1 || !Number.isSafeInteger(this[configKey].maxResults) || this[configKey].maxResults < 1 || !Number.isSafeInteger(this[configKey].maxSnippetBytes) || this[configKey].maxSnippetBytes < 1) throw limit("Search limits must be positive safe integers.");
+		if (tokenize(query).length === 0) throw new LlmWikiError("INVALID_PAGE", "Search query must contain at least one Unicode letter or number.");
+		return this.enqueue(async (paths) => {
+			return [...searchBuiltIndex(await this.ensureIndex(paths, signal), query, {
+				limit: limitValue,
+				maxResults: this[configKey].maxResults,
+				maxSnippetBytes: this[configKey].maxSnippetBytes,
+				...signal === void 0 ? {} : { signal }
+			})];
+		}, signal);
+	}
+	async reindex(signal) {
+		return this.enqueue(async (paths) => {
+			await countFiles(paths.pages, ".md", paths, signal);
+			await this.indexTargetPresence(paths, signal);
+			const built = await buildSearchIndex(paths, signal, void 0, paths.rootDirectory);
+			await writeIndex(paths, built, signal, paths.rootDirectory);
+			return {
+				pageCount: built.search.pageFingerprints.length,
+				sectionCount: built.search.sections.length,
+				formatVersion: built.search.formatVersion
+			};
+		}, signal);
+	}
+	async indexTargetPresence(paths, signal) {
+		const [searchPresent, statePresent] = await allSettledOnFailure([regularFile(paths.indexFile("search.json"), paths, signal), regularFile(paths.indexFile("state.json"), paths, signal)]);
+		return [searchPresent, statePresent];
+	}
+	async ensureIndex(paths, signal) {
+		await countFiles(paths.pages, ".md", paths, signal);
+		const expected = await buildSearchIndex(paths, signal, void 0, paths.rootDirectory);
+		const [searchPresent, statePresent] = await this.indexTargetPresence(paths, signal);
+		if (searchPresent && statePresent) try {
+			const [searchBytes, stateBytes] = await allSettledOnFailure([readBytes(paths, paths.indexFile("search.json"), signal), readBytes(paths, paths.indexFile("state.json"), signal)]);
+			if (searchBytes === null || stateBytes === null) unsafe();
+			const search = trustedSearchIndex(searchBytes, stateBytes, expected);
+			await validateBuiltIndexSnapshot(paths, expected, signal, paths.rootDirectory);
+			if (search !== null) return search;
+		} catch (cause) {
+			throwIfAborted(signal);
+			if (!(cause instanceof LlmWikiError && cause.code === "INDEX_CORRUPT") && !isMissing(cause)) throw cause;
+		}
+		await this.indexTargetPresence(paths, signal);
+		await writeIndex(paths, expected, signal, paths.rootDirectory);
+		return expected.search;
+	}
+	async indexStatus(paths, signal) {
+		const [searchPresent, statePresent] = await this.indexTargetPresence(paths, signal);
+		if (!searchPresent && !statePresent) return EMPTY_INDEX_STATUS;
+		if (!searchPresent || !statePresent) return {
+			present: true,
+			fresh: false,
+			formatVersion: null,
+			sectionCount: 0
+		};
+		try {
+			const [searchBytes, stateBytes] = await allSettledOnFailure([readBytes(paths, paths.indexFile("search.json"), signal), readBytes(paths, paths.indexFile("state.json"), signal)]);
+			if (searchBytes === null || stateBytes === null) unsafe();
+			parseSearchIndex(searchBytes);
+			parseIndexState(stateBytes);
+			let expected;
+			try {
+				expected = await buildSearchIndex(paths, signal, void 0, paths.rootDirectory);
+			} catch (cause) {
+				throwIfAborted(signal);
+				if (cause instanceof LlmWikiError && (cause.code === "INVALID_PAGE" || cause.code === "INVALID_PATH")) return {
+					present: true,
+					fresh: false,
+					formatVersion: 1,
+					sectionCount: 0
+				};
+				throw cause;
+			}
+			const search = trustedSearchIndex(searchBytes, stateBytes, expected);
+			await validateBuiltIndexSnapshot(paths, expected, signal, paths.rootDirectory);
+			return {
+				present: true,
+				fresh: search !== null,
+				formatVersion: 1,
+				sectionCount: expected.search.sections.length
+			};
+		} catch (cause) {
+			throwIfAborted(signal);
+			if (isMissing(cause) || cause instanceof LlmWikiError && cause.code === "INDEX_CORRUPT") return {
+				present: true,
+				fresh: false,
+				formatVersion: null,
+				sectionCount: 0
+			};
+			throw cause;
+		}
+	}
+};
+//#endregion
+//#region src/presentation.ts
+const PRESENTATION = Object.freeze({
+	llmwiki_status: {
+		title: "Inspect wiki status",
+		kind: "read"
+	},
+	llmwiki_add_source: {
+		title: "Preserve wiki source",
+		kind: "edit"
+	},
+	llmwiki_list_sources: {
+		title: "List wiki sources",
+		kind: "read"
+	},
+	llmwiki_read_source: {
+		title: "Read wiki source",
+		kind: "read"
+	},
+	llmwiki_search: {
+		title: "Search wiki",
+		kind: "search"
+	},
+	llmwiki_list_pages: {
+		title: "List wiki pages",
+		kind: "read"
+	},
+	llmwiki_read_page: {
+		title: "Read wiki page",
+		kind: "read"
+	},
+	llmwiki_upsert_page: {
+		title: "Update wiki page",
+		kind: "edit"
+	},
+	llmwiki_lint: {
+		title: "Lint wiki",
+		kind: "read"
+	}
+});
+function salientInput(name, args) {
+	switch (name) {
+		case "llmwiki_add_source": return typeof args.name === "string" ? args.name : void 0;
+		case "llmwiki_read_source": return typeof args.id === "string" ? args.id : void 0;
+		case "llmwiki_search": return typeof args.query === "string" ? args.query : void 0;
+		case "llmwiki_read_page":
+		case "llmwiki_upsert_page": return typeof args.id === "string" ? args.id : void 0;
+		default: return;
+	}
+}
+function presentLlmWikiCall(name, args) {
+	const presentation = PRESENTATION[name];
+	return {
+		card: "generic",
+		title: presentation.title,
+		kind: presentation.kind,
+		...salientInput(name, args) === void 0 ? {} : { rawInput: salientInput(name, args) }
+	};
+}
+function presentLlmWikiResult(name, _args, result) {
+	const presentation = PRESENTATION[name];
+	return {
+		card: "generic",
+		title: result.isError ? `${presentation.title} failed` : presentation.title
+	};
+}
+//#endregion
+//#region src/tools.ts
+const requiredString = () => ({
+	type: "string",
+	required: true
+});
+const requiredInteger = () => ({
+	type: "integer",
+	required: true
+});
+const requiredNumber = () => ({
+	type: "number",
+	required: true
+});
+const requiredBoolean = () => ({
+	type: "boolean",
+	required: true
+});
+const requiredStringArray = () => ({
+	type: "array",
+	required: true,
+	items: { type: "string" }
+});
+const closed = (properties) => ({
+	type: "object",
+	additionalProperties: false,
+	properties
+});
+const requiredClosed = (properties) => ({
+	...closed(properties),
+	required: true
+});
+const requiredNullableString = {
+	required: true,
+	oneOf: [{ type: "string" }, { type: "null" }]
+};
+const requiredNullableInteger = {
+	required: true,
+	oneOf: [{ type: "integer" }, { type: "null" }]
+};
+const optionalNullableString = { oneOf: [{ type: "string" }, { type: "null" }] };
+const optionalString = { type: "string" };
+const catalogParameters = {
+	limit: {
+		type: "integer",
+		description: "Optional catalog page size; defaults to deployment maxResults and is bounded by it."
+	},
+	cursor: {
+		type: "string",
+		description: "Optional opaque cursor returned by the same catalog tool."
+	}
+};
+const sourceCatalogPageSchema = closed({
+	items: {
+		type: "array",
+		required: true,
+		items: closed({
+			id: requiredString(),
+			name: requiredString(),
+			mediaType: requiredString(),
+			byteCount: requiredInteger(),
+			capturedAt: requiredString(),
+			origin: optionalString
+		})
+	},
+	nextCursor: requiredNullableString
+});
+const pageCatalogPageSchema = closed({
+	items: {
+		type: "array",
+		required: true,
+		items: closed({
+			id: requiredString(),
+			title: requiredString(),
+			summary: requiredString(),
+			sources: requiredStringArray(),
+			byteCount: requiredInteger(),
+			sha256: requiredString()
+		})
+	},
+	nextCursor: requiredNullableString
+});
+const indexSchema = requiredClosed({
+	present: requiredBoolean(),
+	fresh: requiredBoolean(),
+	formatVersion: requiredNullableInteger,
+	sectionCount: requiredInteger()
+});
+const metadataSchema = requiredClosed({
+	id: requiredString(),
+	name: requiredString(),
+	mediaType: requiredString(),
+	byteCount: requiredInteger(),
+	capturedAt: requiredString(),
+	origin: optionalNullableString
+});
+const render = (_args, value) => [{
+	type: "text",
+	text: JSON.stringify(value)
+}];
+function stableFailure(cause) {
+	if (isLlmWikiError(cause)) throw new LlmWikiError(cause.code, cause.message);
+	throw cause;
+}
+async function call(operation) {
+	try {
+		return await operation();
+	} catch (cause) {
+		stableFailure(cause);
+	}
+}
+function presentation(name) {
+	return {
+		presentCall: (args) => presentLlmWikiCall(name, args),
+		presentResult: (args, result) => presentLlmWikiResult(name, args, result)
+	};
+}
+function registerLlmWikiTools(ctx) {
+	ctx.tools.register(defineTool({
+		name: "llmwiki_status",
+		description: "Discover wiki initialization, schema, durable record counts, and derived-index freshness before relying on wiki knowledge. Read-only; no approval or filesystem capability is requested.",
+		parameters: {},
+		output: {
+			schema: closed({
+				initialized: requiredBoolean(),
+				sourceCount: requiredInteger(),
+				pageCount: requiredInteger(),
+				schemaText: requiredNullableString,
+				index: indexSchema
+			}),
+			render
+		},
+		execute: (_args, exec) => call(async () => {
+			const status = await ctx.llmwiki.status(exec.signal);
+			return {
+				initialized: status.initialized,
+				sourceCount: status.sourceCount,
+				pageCount: status.pageCount,
+				schemaText: status.schemaText,
+				index: {
+					present: status.index.present,
+					fresh: status.index.fresh,
+					formatVersion: status.index.formatVersion,
+					sectionCount: status.index.sectionCount
+				}
+			};
+		}),
+		isConcurrencySafe: () => true,
+		...presentation("llmwiki_status")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_add_source",
+		description: "Preserve exact UTF-8 evidence supplied in content as an immutable source record. This mutates wiki storage and should be used only with authorized evidence; it cannot read host paths. Completion returns the durable source artifact ID and dedupe state.",
+		parameters: {
+			name: {
+				type: "string",
+				required: true,
+				description: "Non-empty human-readable source name."
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "Exact UTF-8 source content containing at least one byte; whitespace-only content is valid; bounded by deployment maxSourceBytes."
+			},
+			mediaType: {
+				type: "string",
+				description: "Optional non-empty media type; defaults to UTF-8 plain text."
+			},
+			origin: {
+				type: "string",
+				description: "Optional provenance label or URL containing at least one non-whitespace character; never used as a host path."
+			}
+		},
+		output: {
+			schema: closed({
+				id: requiredString(),
+				deduplicated: requiredBoolean(),
+				metadata: metadataSchema
+			}),
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			const receipt = await ctx.llmwiki.addSource({
+				name: args.name,
+				content: args.content,
+				...args.mediaType === void 0 ? {} : { mediaType: args.mediaType },
+				...args.origin === void 0 ? {} : { origin: args.origin }
+			}, exec.signal);
+			return {
+				id: receipt.id,
+				deduplicated: receipt.deduplicated,
+				metadata: {
+					id: receipt.metadata.id,
+					name: receipt.metadata.name,
+					mediaType: receipt.metadata.mediaType,
+					byteCount: receipt.metadata.byteCount,
+					capturedAt: receipt.metadata.capturedAt,
+					...receipt.metadata.origin === void 0 ? {} : { origin: receipt.metadata.origin }
+				}
+			};
+		}),
+		...presentation("llmwiki_add_source")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_list_sources",
+		description: "List immutable source records in deterministic ID order for recovery and inventory. Read-only; returns bounded safe metadata without content or host paths.",
+		parameters: catalogParameters,
+		output: {
+			schema: sourceCatalogPageSchema,
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			const page = await ctx.llmwiki.listSources({
+				...args.limit === void 0 ? {} : { limit: args.limit },
+				...args.cursor === void 0 ? {} : { cursor: args.cursor }
+			}, exec.signal);
+			return {
+				items: page.items.map((item) => ({
+					id: item.id,
+					name: item.name,
+					mediaType: item.mediaType,
+					byteCount: item.byteCount,
+					capturedAt: item.capturedAt,
+					...item.origin === void 0 ? {} : { origin: item.origin }
+				})),
+				nextCursor: page.nextCursor
+			};
+		}),
+		isConcurrencySafe: () => true,
+		...presentation("llmwiki_list_sources")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_read_source",
+		description: "Read immutable source evidence by exact source ID, optionally using a configured byte-bounded range, and return provenance metadata with the content artifact. First access can create the configured host root, wiki directories, and default schema outside DSH filesystem approval, even if the requested source is missing; existing source records are not modified. A non-EOF range must fit at least one complete UTF-8 code point or returns LIMIT_EXCEEDED instructing the caller to increase limit.",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Exact 64-character lowercase hexadecimal source ID."
+			},
+			offset: {
+				type: "integer",
+				description: "Optional non-negative zero-based UTF-8 byte offset; defaults to 0."
+			},
+			limit: {
+				type: "integer",
+				description: "Optional positive maximum bytes; defaults to deployment maxSourceBytes and is bounded by it. Increase it if no complete UTF-8 code point fits."
+			}
+		},
+		output: {
+			schema: closed({
+				id: requiredString(),
+				content: requiredString(),
+				metadata: metadataSchema,
+				byteStart: requiredInteger(),
+				byteEnd: requiredInteger(),
+				byteCount: requiredInteger()
+			}),
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			const range = args.offset === void 0 && args.limit === void 0 ? void 0 : {
+				...args.offset === void 0 ? {} : { offset: args.offset },
+				...args.limit === void 0 ? {} : { limit: args.limit }
+			};
+			const source = await ctx.llmwiki.readSource(sourceId(args.id), range, exec.signal);
+			return {
+				id: source.id,
+				content: source.content,
+				metadata: {
+					id: source.metadata.id,
+					name: source.metadata.name,
+					mediaType: source.metadata.mediaType,
+					byteCount: source.metadata.byteCount,
+					capturedAt: source.metadata.capturedAt,
+					...source.metadata.origin === void 0 ? {} : { origin: source.metadata.origin }
+				},
+				byteStart: source.byteStart,
+				byteEnd: source.byteEnd,
+				byteCount: source.byteCount
+			};
+		}),
+		isConcurrencySafe: () => true,
+		...presentation("llmwiki_read_source")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_search",
+		description: "Search the derived section index first for ranked source-linked page-section matches. May rebuild only stale derived index artifacts; it does not alter durable pages or sources. Results are capped by deployment maxResults and snippets by maxSnippetBytes.",
+		parameters: {
+			query: {
+				type: "string",
+				required: true,
+				description: "Non-empty Unicode lexical query containing at least one letter or number."
+			},
+			limit: {
+				type: "integer",
+				description: "Optional positive result cap up to 100, additionally bounded by deployment maxResults."
+			}
+		},
+		output: {
+			schema: {
+				type: "array",
+				items: closed({
+					pageId: requiredString(),
+					title: requiredString(),
+					headingTrail: requiredStringArray(),
+					startLine: requiredInteger(),
+					score: requiredNumber(),
+					snippet: requiredString(),
+					sourceIds: requiredStringArray()
+				})
+			},
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			return (await ctx.llmwiki.search(args.query, args.limit, exec.signal)).map((hit) => ({
+				pageId: hit.pageId,
+				title: hit.title,
+				headingTrail: [...hit.headingTrail],
+				startLine: hit.startLine,
+				score: hit.score,
+				snippet: hit.snippet,
+				sourceIds: [...hit.sourceIds]
+			}));
+		}),
+		...presentation("llmwiki_search")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_list_pages",
+		description: "List durable wiki pages in deterministic ID order for recovery and inventory. Read-only; returns bounded metadata and exact byte hashes without page content.",
+		parameters: catalogParameters,
+		output: {
+			schema: pageCatalogPageSchema,
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			const page = await ctx.llmwiki.listPages({
+				...args.limit === void 0 ? {} : { limit: args.limit },
+				...args.cursor === void 0 ? {} : { cursor: args.cursor }
+			}, exec.signal);
+			return {
+				items: page.items.map((item) => ({
+					id: item.id,
+					title: item.title,
+					summary: item.summary,
+					sources: [...item.sources],
+					byteCount: item.byteCount,
+					sha256: item.sha256
+				})),
+				nextCursor: page.nextCursor
+			};
+		}),
+		isConcurrencySafe: () => true,
+		...presentation("llmwiki_list_pages")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_read_page",
+		description: "Read one synthesized source-linked wiki page by normalized logical page ID; inspect its cited immutable source records when evaluating claim support. First access can create the configured host root, wiki directories, and default schema outside DSH filesystem approval, even if the requested page is missing; existing pages are not modified.",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Non-empty normalized POSIX page ID without a leading slash or .md suffix."
+		} },
+		output: {
+			schema: closed({
+				id: requiredString(),
+				markdown: requiredString(),
+				sha256: requiredString(),
+				metadata: requiredClosed({
+					title: requiredString(),
+					summary: requiredString(),
+					sources: requiredStringArray()
+				})
+			}),
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			const page = await ctx.llmwiki.readPage(pageId(args.id), exec.signal);
+			return {
+				id: page.id,
+				markdown: page.markdown,
+				sha256: page.sha256,
+				metadata: {
+					title: page.metadata.title,
+					summary: page.metadata.summary,
+					sources: [...page.metadata.sources]
+				}
+			};
+		}),
+		isConcurrencySafe: () => true,
+		...presentation("llmwiki_read_page")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_upsert_page",
+		description: "Atomically create or update a synthesized durable Markdown page with a required concurrency precondition: null creates only; the exact current raw-byte SHA-256 updates only. PAGE_CONFLICT requires rereading and reconciling, not automatic retry. This mutation requires existing preserved source IDs but does not verify claim-level support. Use only when the user request authorizes maintenance. Returns the page artifact ID, creation state, and content hash.",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Non-empty normalized POSIX page ID without a leading slash or .md suffix."
+			},
+			expectedSha256: {
+				...requiredNullableString,
+				description: "Required: null for a new page, or the exact current lowercase SHA-256 from llmwiki_read_page or llmwiki_list_pages for an update. On PAGE_CONFLICT, reread and reconcile before another write."
+			},
+			title: {
+				type: "string",
+				required: true,
+				description: "Non-empty concise page title."
+			},
+			summary: {
+				type: "string",
+				required: true,
+				description: "Non-empty concise source-linked summary."
+			},
+			sources: {
+				type: "array",
+				required: true,
+				items: { type: "string" },
+				description: "Non-empty sorted unique 64-character lowercase hexadecimal IDs of existing immutable source records; never invent IDs. Existence is verified, semantic support is not."
+			},
+			body: {
+				type: "string",
+				required: true,
+				description: "Non-empty Markdown body bounded by deployment maxPageBytes after canonical rendering."
+			}
+		},
+		output: {
+			schema: closed({
+				id: requiredString(),
+				created: requiredBoolean(),
+				sha256: requiredString()
+			}),
+			render
+		},
+		execute: (args, exec) => call(async () => {
+			const receipt = await ctx.llmwiki.upsertPage({
+				id: pageId(args.id),
+				expectedSha256: args.expectedSha256,
+				title: args.title,
+				summary: args.summary,
+				sources: args.sources.map(sourceId),
+				body: args.body
+			}, exec.signal);
+			return {
+				id: receipt.id,
+				created: receipt.created,
+				sha256: receipt.sha256
+			};
+		}),
+		...presentation("llmwiki_upsert_page")
+	}));
+	ctx.tools.register(defineTool({
+		name: "llmwiki_lint",
+		description: "Run deterministic model-free read-only structural validation. Reports filesystem, integrity, link, canonical-format, and index diagnostics and progress counts; never makes semantic judgments or fixes, deletes, or rewrites artifacts.",
+		parameters: {},
+		output: {
+			schema: closed({
+				diagnostics: {
+					type: "array",
+					required: true,
+					items: closed({
+						code: requiredString(),
+						severity: {
+							type: "string",
+							required: true,
+							enum: ["error", "warning"]
+						},
+						path: requiredString(),
+						line: requiredNullableInteger,
+						message: requiredString()
+					})
+				},
+				errorCount: requiredInteger(),
+				warningCount: requiredInteger(),
+				filesExamined: requiredInteger()
+			}),
+			render
+		},
+		execute: (_args, exec) => call(async () => {
+			const report = await ctx.llmwiki.lint(exec.signal);
+			return {
+				diagnostics: report.diagnostics.map((diagnostic) => ({
+					code: diagnostic.code,
+					severity: diagnostic.severity,
+					path: diagnostic.path,
+					line: diagnostic.line ?? null,
+					message: diagnostic.message
+				})),
+				errorCount: report.errorCount,
+				warningCount: report.warningCount,
+				filesExamined: report.filesExamined
+			};
+		}),
+		isConcurrencySafe: () => true,
+		...presentation("llmwiki_lint")
+	}));
+}
+//#endregion
+//#region src/index.ts
+const name = "llmwiki";
+const inject = [
+	"tools",
+	"commands",
+	"systemPrompt"
+];
+function apply(ctx, config = {}) {
+	const resolvedConfig = resolveConfig(config);
+	new LlmWikiService(ctx, resolvedConfig);
+	registerLlmWikiPrompt(ctx);
+	registerLlmWikiTools(ctx);
+	registerLlmWikiCommand(ctx, resolvedConfig);
+}
+//#endregion
+export { Config, LLMWIKI_ERROR_CODES, LlmWikiError, LlmWikiService, apply, inject, isLlmWikiError, isPageId, isSourceId, name, pageId, sourceId };
+
+//# sourceMappingURL=index.js.map