@hollware/server 0.4.0 → 0.6.0

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { A as effectiveScopes, C as revisionTags, D as tokens, E as sites, O as users, S as reviews, T as schedules, _ as entries, b as outbox, g as deliveries, j as isRole, k as ROLE_SCOPES, l as membershipsOf, n as createInvitation, s as findSession, v as invitations, w as revisions, x as publications, y as members } from "./store-CsuER6J7.mjs";
-import { EVENT_ID_HEADER, HollwareError, OPERATIONS, SCOPES, SIGNATURE_HEADER, TIMESTAMP_HEADER, describeBuiltInContracts, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isPersonalToken, isReadToken, isScope, listEntries, newId, processMarkdown, publish, renderHtml, resolveConfig, runContracts, signWebhook, sizeLimitViolation, uniqueSlugViolation, uniqueTranslationViolation } from "@hollware/core";
+import { A as users, C as reviewComments, D as schedules, E as revisions, M as effectiveScopes, N as isRole, O as sites, S as publications, T as revisionTags, _ as entries, b as members, g as deliveries, j as ROLE_SCOPES, k as tokens, l as membershipsOf, n as createInvitation, s as findSession, v as entryEmbeddings, w as reviews, x as outbox, y as invitations } from "./store-CYMjP0iN.mjs";
+import { CHUNKER_VERSION, EVENT_ID_HEADER, HollwareError, OPERATIONS, SCOPES, SIGNATURE_HEADER, TIMESTAMP_HEADER, chunksOf, describeBuiltInContracts, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, newId, processMarkdown, publish, renderHtml, resolveConfig, runContracts, search, signWebhook, sizeLimitViolation, uniqueSlugViolation, uniqueTranslationViolation } from "@hollware/core";
 import { Hono } from "hono";
 import { drizzle } from "drizzle-orm/d1";
-import { and, desc, eq, getTableColumns, gt, inArray, isNull, lte, ne, or, sql } from "drizzle-orm";
+import { and, asc, desc, eq, getTableColumns, gt, inArray, isNotNull, isNull, lte, ne, or, sql } from "drizzle-orm";
 import { alias } from "drizzle-orm/sqlite-core";
 import { AuthorizationError, CimdFetchError, OAuthAuthorizationServer, OAuthResourceServer, authorizationErrorRedirect } from "@cloudflare/workers-oauth-provider";
 import { getCookie } from "hono/cookie";
@@ -10,7 +10,7 @@ import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, McpServer, accepted
 import * as z from "zod";
 import { WorkerEntrypoint } from "cloudflare:workers";
 //#region package.json
-var version = "0.4.0";
+var version = "0.6.0";
 //#endregion
 //#region src/auth/responses.ts
 /** The challenge of every 401 and 403 (RFC 6750). */
@@ -632,6 +632,61 @@ function listEntriesQuery(db, site, query, cursor) {
 		cursor === null ? void 0 : sql`(${sortKey}, ${entries.id}) < (${cursor.key}, ${cursor.id})`
 	]).orderBy(desc(sortKey), desc(entries.id)).limit(query.limit + 1);
 }
+/**
+* The FTS5 query of what someone typed: each of its words as a quoted string, so that FTS5's own
+* syntax (`AND`, `NEAR`, `*`, quotes) is never read from it, and every word must match. Empty when
+* it holds no word.
+*/
+function ftsQuery(text) {
+	return (text.match(/[\p{L}\p{N}_]+/gu) ?? []).map((word) => `"${word}"`).join(" ");
+}
+/** The weights of the columns of `entries_fts` in bm25: title, tags, then the text. */
+const BM25 = sql.raw("bm25(entries_fts, 10.0, 4.0, 1.0)");
+async function searchEntries(db, site, query) {
+	const match = ftsQuery(query.text);
+	if (match === "") return [];
+	const hits = await db.all(sql`
+    select entry_id, snippet(entries_fts, 2, '[', ']', '…', 16) as snippet, ${BM25} as rank
+    from entries_fts
+    where entries_fts match ${match} and site_id = ${site}
+      ${query.collection === void 0 ? sql`` : sql`and collection = ${query.collection}`}
+      ${query.locale === void 0 ? sql`` : sql`and locale = ${query.locale}`}
+    order by rank
+    limit ${query.limit}
+  `);
+	if (hits.length === 0) return [];
+	const rows = await summaryQuery(db, "published", [eq(entries.siteId, site), inArray(entries.id, hits.map((hit) => hit.entry_id))]);
+	const byId = new Map(rows.map((row) => [row.entry.id, toEntrySummaryView(row)]));
+	return hits.flatMap((hit) => {
+		const entry = byId.get(hit.entry_id);
+		return entry === void 0 ? [] : [{
+			entry,
+			snippet: hit.snippet,
+			score: -hit.rank
+		}];
+	});
+}
+/** The entries of those ids that the view has, in the order of the ids; the others are left out. */
+async function findSummaries(db, site, ids, view) {
+	if (ids.length === 0) return [];
+	const rows = await summaryQuery(db, view, [eq(entries.siteId, site), inArray(entries.id, [...ids])]);
+	const byId = new Map(rows.map((row) => [row.entry.id, toEntrySummaryView(row)]));
+	return ids.flatMap((id) => {
+		const entry = byId.get(id);
+		return entry === void 0 ? [] : [entry];
+	});
+}
+/** The entries closest to one, closest first, as its vectors found them (ADR-030); `[]` without. */
+async function relatedOf(db, site, entryId) {
+	const [row] = await db.select({ related: entryEmbeddings.related }).from(entryEmbeddings).where(and(eq(entryEmbeddings.siteId, site), eq(entryEmbeddings.entryId, entryId))).limit(1);
+	if (row === void 0) return [];
+	const parsed = JSON.parse(row.related);
+	if (!Array.isArray(parsed)) return [];
+	return parsed.flatMap((item) => typeof item === "object" && item !== null && "id" in item && "score" in item && typeof item.id === "string" && typeof item.score === "number" ? [{
+		id: item.id,
+		score: item.score
+	}] : []);
+}
 async function listEntries$2(db, site, query) {
 	if (!Number.isInteger(query.limit) || query.limit < 1) throw new HollwareError("invalid_input", `The limit ${query.limit} is not a whole number of at least 1.`, "Ask for at least one entry per page.");
 	const cursor = query.cursor === void 0 ? null : decodeCursor(query.cursor, query.view);
@@ -986,7 +1041,7 @@ async function pendingOf(db, site, entryId) {
 	const [row] = await db.select(COLUMNS).from(reviews).innerJoin(users, eq(users.id, reviews.requestedBy)).where(and(eq(reviews.siteId, site), eq(reviews.entryId, entryId), eq(reviews.status, "pending"))).limit(1);
 	return row === void 0 ? null : toReview(row);
 }
-async function requestReview(db, clock, site, write, whyNothingChanged) {
+async function requestReview$1(db, clock, site, write, whyNothingChanged) {
 	const now = clock.now().toISOString();
 	const row = {
 		id: newId("rvw"),
@@ -1048,6 +1103,59 @@ async function requestChanges$1(db, clock, site, write) {
 		review
 	};
 }
+function metaOf(text) {
+	if (text === null) return null;
+	const parsed = JSON.parse(text);
+	return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? Object.fromEntries(Object.entries(parsed)) : null;
+}
+const COMMENT_COLUMNS = {
+	...getTableColumns(reviewComments),
+	authorName: users.name
+};
+function toComment(row) {
+	return {
+		id: row.id,
+		reviewId: row.reviewId,
+		authorId: row.authorId,
+		authorName: row.authorName,
+		authorMeta: metaOf(row.authorMeta),
+		body: row.body,
+		createdAt: row.createdAt
+	};
+}
+/**
+* Adds a comment to a review in one statement that inserts only while the review is pending, so a
+* decision that lands first leaves no comment behind it.
+*/
+async function commentReview$1(db, clock, site, write) {
+	const id = newId("rvc");
+	const now = clock.now().toISOString();
+	const meta = write.actor.meta === null ? null : JSON.stringify(write.actor.meta);
+	if ((await db.all(sql`
+    insert into ${reviewComments}
+      (id, site_id, review_id, author_id, author_meta, body, created_at, updated_at)
+    select ${id}, ${site}, ${write.reviewId}, ${write.actor.userId}, ${meta}, ${write.body}, ${now}, ${now}
+    where exists (select 1 from ${reviews} where ${and(eq(reviews.id, write.reviewId), eq(reviews.siteId, site), eq(reviews.status, "pending"))})
+    returning id
+  `)).length === 0) return { outcome: await findReview(db, site, write.reviewId) === null ? "not_found" : "not_pending" };
+	const [row] = await db.select(COMMENT_COLUMNS).from(reviewComments).innerJoin(users, eq(users.id, reviewComments.authorId)).where(and(eq(reviewComments.siteId, site), eq(reviewComments.id, id))).limit(1);
+	if (row === void 0) throw new Error(`The comment ${id} that was just written is not there`);
+	return {
+		outcome: "commented",
+		comment: toComment(row)
+	};
+}
+async function reviewCommentsOf(db, site, reviewIds) {
+	const byReview = /* @__PURE__ */ new Map();
+	if (reviewIds.length === 0) return byReview;
+	const rows = await db.select(COMMENT_COLUMNS).from(reviewComments).innerJoin(users, eq(users.id, reviewComments.authorId)).where(and(eq(reviewComments.siteId, site), inArray(reviewComments.reviewId, [...reviewIds]))).orderBy(asc(reviewComments.createdAt), asc(reviewComments.id));
+	for (const row of rows) {
+		const list = byReview.get(row.reviewId) ?? [];
+		list.push(toComment(row));
+		byReview.set(row.reviewId, list);
+	}
+	return byReview;
+}
 //#endregion
 //#region src/db/size.ts
 /**
@@ -1442,6 +1550,9 @@ function createD1Store(db, options = {}) {
 		findEntry: (site, ref, view) => findEntry(database, site, ref, view),
 		findEntryById: (site, id, view) => findEntryById(database, site, id, view),
 		listEntries: (site, query) => listEntries$2(database, site, query),
+		searchEntries: (site, query) => searchEntries(database, site, query),
+		findSummaries: (site, ids, view) => findSummaries(database, site, ids, view),
+		relatedOf: (site, entryId) => relatedOf(database, site, entryId),
 		listTranslations: (site, collection, translationGroup, view) => listTranslations(database, site, collection, translationGroup, view),
 		lookup: (site) => lookup(database, site),
 		lastPublication: (site, entryId) => lastPublication(database, site, entryId),
@@ -1453,10 +1564,12 @@ function createD1Store(db, options = {}) {
 		dueSchedules: (site, now) => dueSchedules(database, site, now),
 		cancelSchedule: (site, entryId) => cancelSchedule(database, clock, site, entryId),
 		unpublish: (site, write) => unpublish$1(database, clock, site, write),
-		requestReview: (site, write) => requestReview(database, clock, site, write, () => whyNothingChanged(database, site, write.entryId)),
+		requestReview: (site, write) => requestReview$1(database, clock, site, write, () => whyNothingChanged(database, site, write.entryId)),
 		findReview: (site, id) => findReview(database, site, id),
 		listReviews: (site, query) => listReviews$1(database, site, query),
-		requestChanges: (site, write) => requestChanges$1(database, clock, site, write)
+		requestChanges: (site, write) => requestChanges$1(database, clock, site, write),
+		commentReview: (site, write) => commentReview$1(database, clock, site, write),
+		reviewComments: (site, reviewIds) => reviewCommentsOf(database, site, reviewIds)
 	};
 }
 //#endregion
@@ -1515,6 +1628,191 @@ function sqlIncrement() {
 	return sql`${deliveries.attempts} + 1`;
 }
 //#endregion
+//#region src/semantic/index-entry.ts
+/** The id of a piece's vector. */
+function vectorId(entryId, piece) {
+	return `${entryId}:${piece}`;
+}
+function excerptOf(text) {
+	if (text.length <= 200) return text;
+	const cut = text.slice(0, 200);
+	const lastSpace = cut.lastIndexOf(" ");
+	return `${(lastSpace > 0 ? cut.slice(0, lastSpace) : cut).trim()}…`;
+}
+function stringOf(value) {
+	return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+/** The ids of the vectors of `pieces` pieces of an entry, from `from` on. */
+function idsOf(entryId, from, pieces) {
+	return Array.from({ length: Math.max(0, pieces - from) }, (_, offset) => vectorId(entryId, from + offset));
+}
+/** The entries nearest to an entry's summary, in its collection and locale; itself left out. */
+async function nearestTo(semantic, input) {
+	return (await semantic.index.query(input.summary, {
+		topK: 6,
+		site: input.site,
+		collection: input.collection,
+		locale: input.locale,
+		summariesOnly: true
+	})).filter((match) => match.metadata.entry !== input.entryId).slice(0, 5).map((match) => ({
+		id: match.metadata.entry,
+		score: match.score
+	}));
+}
+/**
+* Brings the vectors of one entry in line with what it has published: the pieces of its published
+* revision, embedded with the model of `semantic`. It reads the entry as it is now, so it is right
+* whichever event called it and however late: an entry whose vectors already are of its published
+* revision, model and chunker is `current` and costs no embedding; an entry with nothing published
+* (unpublished, deleted, gone) loses its vectors and its row.
+*/
+async function syncEntryVectors(db, semantic, input) {
+	const { site, entryId, now } = input;
+	const [published] = await db.select({
+		collection: entries.collection,
+		locale: entries.locale,
+		revisionId: revisions.id,
+		frontmatter: revisions.frontmatter,
+		document: revisions.document
+	}).from(entries).innerJoin(revisions, and(eq(revisions.id, entries.publishedRev), eq(revisions.siteId, entries.siteId))).where(and(eq(entries.siteId, site), eq(entries.id, entryId))).limit(1);
+	const [stored] = await db.select({
+		revisionId: entryEmbeddings.revisionId,
+		model: entryEmbeddings.model,
+		chunkerVersion: entryEmbeddings.chunkerVersion,
+		pieces: entryEmbeddings.pieces
+	}).from(entryEmbeddings).where(and(eq(entryEmbeddings.siteId, site), eq(entryEmbeddings.entryId, entryId))).limit(1);
+	if (published === void 0) {
+		if (stored === void 0) return "absent";
+		await semantic.index.remove(idsOf(entryId, 0, stored.pieces));
+		await db.delete(entryEmbeddings).where(and(eq(entryEmbeddings.siteId, site), eq(entryEmbeddings.entryId, entryId)));
+		return "removed";
+	}
+	if (stored !== void 0 && stored.revisionId === published.revisionId && stored.model === semantic.embedder.model && stored.chunkerVersion === CHUNKER_VERSION) return "current";
+	const frontmatter = JSON.parse(published.frontmatter);
+	const document = JSON.parse(published.document);
+	const description = stringOf(frontmatter["description"]);
+	const chunks = chunksOf({
+		title: stringOf(frontmatter["title"]) ?? "",
+		...description === void 0 ? {} : { description },
+		document
+	});
+	const vectors = await semantic.embedder.embed(chunks.map((chunk) => chunk.text));
+	await semantic.index.upsert(chunks.map((chunk) => ({
+		id: vectorId(entryId, chunk.index),
+		values: vectors[chunk.index] ?? [],
+		metadata: {
+			site,
+			entry: entryId,
+			collection: published.collection,
+			locale: published.locale,
+			piece: chunk.index,
+			excerpt: excerptOf(chunk.text)
+		}
+	})));
+	if (stored !== void 0) await semantic.index.remove(idsOf(entryId, chunks.length, stored.pieces));
+	const related = await nearestTo(semantic, {
+		site,
+		entryId,
+		collection: published.collection,
+		locale: published.locale,
+		summary: vectors[0] ?? []
+	});
+	const row = {
+		related: JSON.stringify(related),
+		revisionId: published.revisionId,
+		model: semantic.embedder.model,
+		chunkerVersion: CHUNKER_VERSION,
+		pieces: chunks.length,
+		updatedAt: now
+	};
+	await db.insert(entryEmbeddings).values({
+		id: newId("emb"),
+		siteId: site,
+		entryId,
+		createdAt: now,
+		...row
+	}).onConflictDoUpdate({
+		target: [entryEmbeddings.siteId, entryEmbeddings.entryId],
+		set: row
+	});
+	return "indexed";
+}
+/**
+* The entries whose vectors are not those of what they publish: published with no vectors (before
+* the Worker had semantic search, or an event that never reached the subscriber), of another
+* revision, model or chunker; and entries with vectors and nothing published. At most `limit`.
+*/
+async function staleEntries(db, input) {
+	const { site, model, limit } = input;
+	const published = await db.select({ id: entries.id }).from(entries).leftJoin(entryEmbeddings, and(eq(entryEmbeddings.entryId, entries.id), eq(entryEmbeddings.siteId, entries.siteId))).where(and(eq(entries.siteId, site), isNotNull(entries.publishedRev), or(isNull(entryEmbeddings.id), ne(entryEmbeddings.revisionId, entries.publishedRev), ne(entryEmbeddings.model, model), ne(entryEmbeddings.chunkerVersion, CHUNKER_VERSION)))).limit(limit);
+	const left = limit - published.length;
+	const orphans = left <= 0 ? [] : await db.select({ id: entryEmbeddings.entryId }).from(entryEmbeddings).innerJoin(entries, and(eq(entries.id, entryEmbeddings.entryId), eq(entries.siteId, entryEmbeddings.siteId))).where(and(eq(entryEmbeddings.siteId, site), isNull(entries.publishedRev))).limit(left);
+	return [...published, ...orphans].map((row) => row.id);
+}
+/**
+* What the cron trigger does for the vectors of a site: brings at most `limit` stale entries in
+* line, so that a site that turns semantic search on, or changes its model, is indexed a few
+* entries a minute without a command. An entry that fails is left for the next run.
+*/
+async function healVectors(db, semantic, input) {
+	const ids = await staleEntries(db, {
+		site: input.site,
+		model: semantic.embedder.model,
+		limit: input.limit ?? 20
+	});
+	let failed = 0;
+	for (const entryId of ids) await syncEntryVectors(db, semantic, {
+		site: input.site,
+		entryId,
+		now: input.now
+	}).catch(() => {
+		failed += 1;
+	});
+	return {
+		synced: ids.length - failed,
+		failed
+	};
+}
+/** How long an entry with no related entries waits before they are looked for again. */
+const RELATED_RETRY_MS = 6e5;
+/** How old the related entries of an entry may grow before they are looked for again. */
+const RELATED_REFRESH_MS = 864e5;
+/**
+* What the cron trigger does for related entries: it finds them again for at most `limit`
+* entries of the site, oldest first, whose related entries are a day old, or empty for ten
+* minutes. Vectorize shows a vector seconds after it was written, so entries indexed together
+* miss each other at first; and an entry published later belongs among the related entries of
+* those before it. Each keeps its vectors: only its summary is read back and compared.
+*/
+async function refreshRelated(db, semantic, input) {
+	const now = Date.parse(input.now);
+	const retryBefore = (/* @__PURE__ */ new Date(now - RELATED_RETRY_MS)).toISOString();
+	const refreshBefore = (/* @__PURE__ */ new Date(now - RELATED_REFRESH_MS)).toISOString();
+	const rows = await db.select({
+		entryId: entryEmbeddings.entryId,
+		collection: entries.collection,
+		locale: entries.locale
+	}).from(entryEmbeddings).innerJoin(entries, and(eq(entries.id, entryEmbeddings.entryId), eq(entries.siteId, entryEmbeddings.siteId))).where(and(eq(entryEmbeddings.siteId, input.site), isNotNull(entries.publishedRev), or(and(eq(entryEmbeddings.related, "[]"), lte(entryEmbeddings.updatedAt, retryBefore)), lte(entryEmbeddings.updatedAt, refreshBefore)))).orderBy(entryEmbeddings.updatedAt).limit(input.limit ?? 10);
+	if (rows.length === 0) return 0;
+	const summaries = new Map((await semantic.index.get(rows.map((row) => vectorId(row.entryId, 0)))).map((vector) => [vector.id, vector.values]));
+	let refreshed = 0;
+	for (const row of rows) {
+		const summary = summaries.get(vectorId(row.entryId, 0));
+		if (summary === void 0) continue;
+		const related = await nearestTo(semantic, {
+			site: input.site,
+			...row,
+			summary
+		});
+		await db.update(entryEmbeddings).set({
+			related: JSON.stringify(related),
+			updatedAt: input.now
+		}).where(and(eq(entryEmbeddings.siteId, input.site), eq(entryEmbeddings.entryId, row.entryId)));
+		refreshed += 1;
+	}
+	return refreshed;
+}
+//#endregion
 //#region src/events/deliver.ts
 /** Where IndexNow takes the URLs that changed. */
 const INDEXNOW_ENDPOINT = "https://api.indexnow.org/indexnow";
@@ -1566,6 +1864,17 @@ function subscribersOf(deps) {
 			}
 		});
 	}
+	const semantic = deps.semantic;
+	if (semantic !== void 0 && semantic !== null) subscribers.push({
+		name: "vectors",
+		async send(payload) {
+			await syncEntryVectors(deps.db, semantic, {
+				site: site.key,
+				entryId: payload.entry.id,
+				now: deps.clock.now().toISOString()
+			});
+		}
+	});
 	return subscribers;
 }
 /**
@@ -2040,6 +2349,208 @@ function installAdminApi(app, options) {
 	}));
 }
 //#endregion
+//#region src/semantic/cloudflare.ts
+/** The embedding model when the config names none: multilingual, so Spanish finds English. */
+const DEFAULT_EMBEDDING_MODEL = "@cf/baai/bge-m3";
+function isRecord$3(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Workers AI as an embedder: `{ data: number[][] }` for a batch of texts. */
+function workersAiEmbedder(ai, model) {
+	return {
+		model,
+		async embed(texts) {
+			if (texts.length === 0) return [];
+			const answer = await ai.run(model, { text: [...texts] });
+			const data = isRecord$3(answer) ? answer["data"] : void 0;
+			if (!Array.isArray(data) || data.length !== texts.length) throw new Error(`${model} answered no vector for each of ${texts.length} texts`);
+			return data.map((vector) => {
+				if (!Array.isArray(vector)) throw new Error(`${model} answered a vector that is no list`);
+				return vector.map(Number);
+			});
+		}
+	};
+}
+function metadataOf(raw) {
+	if (raw === void 0) return null;
+	const { site, entry, collection, locale, piece, excerpt } = raw;
+	if (typeof excerpt !== "string" || typeof site !== "string" || typeof entry !== "string" || typeof collection !== "string" || typeof locale !== "string" || typeof piece !== "number") return null;
+	return {
+		site,
+		entry,
+		collection,
+		locale,
+		piece,
+		excerpt
+	};
+}
+/** Vectorize as the index. Its metadata indexes on site, collection, locale and piece filter. */
+function vectorizeIndex(binding) {
+	return {
+		async upsert(vectors) {
+			if (vectors.length === 0) return;
+			await binding.upsert(vectors.map((vector) => ({
+				id: vector.id,
+				values: [...vector.values],
+				metadata: { ...vector.metadata }
+			})));
+		},
+		async remove(ids) {
+			if (ids.length > 0) await binding.deleteByIds([...ids]);
+		},
+		async get(ids) {
+			if (ids.length === 0) return [];
+			return (await binding.getByIds([...ids])).map((vector) => ({
+				id: vector.id,
+				values: Array.from(vector.values)
+			}));
+		},
+		async query(values, options) {
+			return (await binding.query([...values], {
+				topK: options.topK,
+				returnMetadata: "all",
+				filter: {
+					site: options.site,
+					...options.collection === void 0 ? {} : { collection: options.collection },
+					...options.locale === void 0 ? {} : { locale: options.locale },
+					...options.summariesOnly === true ? { piece: 0 } : {}
+				}
+			})).matches.flatMap((match) => {
+				const metadata = metadataOf(match.metadata);
+				return metadata === null ? [] : [{
+					id: match.id,
+					score: match.score,
+					metadata
+				}];
+			});
+		}
+	};
+}
+/** Semantic search over the Worker's bindings, or `null` when it does not have both. */
+function semanticOf(env, model) {
+	const ai = Reflect.get(env, "AI");
+	const vectorize = Reflect.get(env, "VECTORIZE");
+	if (!isRecord$3(ai) || typeof ai["run"] !== "function") return null;
+	if (!isRecord$3(vectorize) || typeof vectorize["query"] !== "function") return null;
+	return {
+		embedder: workersAiEmbedder(ai, model),
+		index: vectorizeIndex(vectorize)
+	};
+}
+/**
+* Semantic search over the Worker's bindings, or `null` without them. The model is the variable
+* `HOLLWARE_EMBEDDING_MODEL`, or `DEFAULT_EMBEDDING_MODEL`; the Vectorize index must have been
+* made for its dimensions, so a new model needs a new index.
+*/
+function semanticOfEnv(env) {
+	const model = Reflect.get(env, "HOLLWARE_EMBEDDING_MODEL");
+	return semanticOf(env, typeof model === "string" && model !== "" ? model : DEFAULT_EMBEDDING_MODEL);
+}
+//#endregion
+//#region src/analytics/cloudflare.ts
+/** The dataset of Analytics Engine when the Worker names none. */
+const DEFAULT_ANALYTICS_DATASET = "hollware_page_views";
+/** Where the SQL API of Analytics Engine answers. */
+function sqlApiUrl(accountId) {
+	return `https://api.cloudflare.com/client/v4/accounts/${accountId}/analytics_engine/sql`;
+}
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Analytics Engine as the writer: one data point per view, indexed by the site (its sampling key),
+* with the path and the country as blobs and a count of 1.
+*/
+function analyticsEngineWriter(binding) {
+	return { record(view) {
+		binding.writeDataPoint({
+			indexes: [view.site],
+			blobs: [view.path, view.country],
+			doubles: [1]
+		});
+	} };
+}
+/**
+* The query of the most read paths. The SQL API takes no parameters, so every value in it is
+* checked first: a site key (`[a-z0-9-]`), a dataset name and two whole numbers.
+*/
+function topPagesSql(dataset, site, query) {
+	if (!/^[a-z_][a-z0-9_]{0,63}$/i.test(dataset)) throw new Error(`No dataset is named ${dataset}`);
+	if (!isSiteKey(site)) throw new Error(`No site key is ${String(site)}`);
+	if (!Number.isInteger(query.days) || query.days < 1 || query.days > 90) throw new Error(`${query.days} days is not a whole number from 1 to 90`);
+	if (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 50) throw new Error(`${query.limit} pages is not a whole number from 1 to 50`);
+	return [
+		"SELECT blob1 AS path, SUM(_sample_interval) AS views",
+		`FROM ${dataset}`,
+		`WHERE index1 = '${site}' AND timestamp > NOW() - INTERVAL '${query.days}' DAY`,
+		"GROUP BY path",
+		"ORDER BY views DESC",
+		`LIMIT ${query.limit}`,
+		"FORMAT JSON"
+	].join(" ");
+}
+/** The SQL API of Analytics Engine as the reader, its answers kept for ten minutes. */
+function sqlApiReader(options) {
+	return { async topPages(site, query) {
+		const sql = topPagesSql(options.dataset, site, query);
+		const key = new Request(`https://hollware.invalid/content-stats/${options.dataset}/${site}?days=${query.days}&limit=${query.limit}`);
+		const cached = await options.cache?.match(key);
+		const answer = cached ?? await options.fetch(new Request(sqlApiUrl(options.accountId), {
+			method: "POST",
+			headers: { authorization: `Bearer ${options.token}` },
+			body: sql
+		}));
+		if (!answer.ok) throw new Error(`The SQL API of Analytics Engine answered ${answer.status}`);
+		const text = await answer.text();
+		if (cached === void 0 && options.cache !== null) await options.cache.put(key, new Response(text, { headers: { "cache-control": `max-age=600` } }));
+		const body = JSON.parse(text);
+		return (isRecord$2(body) && Array.isArray(body["data"]) ? body["data"] : []).flatMap((row) => {
+			if (!isRecord$2(row) || typeof row["path"] !== "string") return [];
+			const views = Number(row["views"]);
+			return Number.isFinite(views) ? [{
+				path: row["path"],
+				views
+			}] : [];
+		});
+	} };
+}
+/** The writer over the Worker's `ANALYTICS` binding, or `null` without one. */
+function analyticsWriterOf(env) {
+	const binding = Reflect.get(env, "ANALYTICS");
+	if (!isRecord$2(binding) || typeof binding["writeDataPoint"] !== "function") return null;
+	return analyticsEngineWriter(binding);
+}
+/**
+* The reader over the Worker's variables: `HOLLWARE_ANALYTICS_ACCOUNT_ID` and the secret
+* `HOLLWARE_ANALYTICS_TOKEN` (an API token with Account Analytics Read), and the dataset of
+* `HOLLWARE_ANALYTICS_DATASET` or the default one. `null` without the account or the token.
+*/
+function analyticsReaderOf(env) {
+	const accountId = Reflect.get(env, "HOLLWARE_ANALYTICS_ACCOUNT_ID");
+	const token = Reflect.get(env, "HOLLWARE_ANALYTICS_TOKEN");
+	const dataset = Reflect.get(env, "HOLLWARE_ANALYTICS_DATASET");
+	if (typeof accountId !== "string" || accountId === "") return null;
+	if (typeof token !== "string" || token === "") return null;
+	return sqlApiReader({
+		accountId,
+		token,
+		dataset: typeof dataset === "string" && dataset !== "" ? dataset : DEFAULT_ANALYTICS_DATASET,
+		fetch: (request) => fetch(request),
+		cache: typeof caches === "undefined" ? null : caches.default
+	});
+}
+//#endregion
+//#region src/ops/invoke.ts
+/**
+* Calls the handler of an operation. This is the one place where the typed pairing of specs and
+* handlers meets a dynamic caller (MCP, the ops API): the caller parsed `input` with the input
+* schema of `spec`, which is the schema that types the handler of the same name.
+*/
+function invoke(handlers, spec, input, context) {
+	const handler = handlers[spec.name];
+	return handler(input, context);
+}
+//#endregion
 //#region src/http/ops-api.ts
 const STATUS$1 = {
 	invalid_input: 400,
@@ -2054,10 +2565,6 @@ function json(body, status = 200) {
 	});
 }
 /** Calls the handler of an operation with input its spec has parsed. */
-function invoke$1(handlers, spec, input, context) {
-	const handler = handlers[spec.name];
-	return handler(input, context);
-}
 function installOpsApi(app, options) {
 	app.post("/v1/ops/:name", async (c) => options.protect(c, async (principal) => {
 		const requestId = c.get("requestId");
@@ -2089,10 +2596,12 @@ function installOpsApi(app, options) {
 			clock: options.clock,
 			client: { name: "hollware-admin" },
 			requestId,
-			notify: options.notify(c, requestId, site.key)
+			notify: options.notify(c, requestId, site.key),
+			semantic: semanticOfEnv(c.env),
+			analytics: analyticsReaderOf(c.env)
 		};
 		try {
-			return json(spec.output.parse(await invoke$1(options.handlers, spec, parsed.data, context)));
+			return json(spec.output.parse(await invoke(options.handlers, spec, parsed.data, context)));
 		} catch (error) {
 			if (error instanceof HollwareError) return json({
 				code: error.code,
@@ -2129,6 +2638,31 @@ const STATUS = {
 	unknown_collection: 404,
 	unknown_locale: 404
 };
+/**
+* A route of the read API whose `HollwareError` (an unknown collection, a limit out of range) is
+* the caller's to read, with its status. It is caught here, in the route: Hono 5 hands an error
+* that a route throws to the app's error handler before any middleware around it sees it, and
+* that handler answers every error with the same 500. The answer says how long the read took on
+* the server, after the token was checked (`Server-Timing: read;dur=<ms>`), so that a client can
+* tell the server's time from the network's.
+*/
+function readRoute(handler) {
+	return async (c) => {
+		const started = Date.now();
+		try {
+			const response = await handler(c);
+			response.headers.set("server-timing", `read;dur=${Date.now() - started}`);
+			return response;
+		} catch (error) {
+			if (!(error instanceof HollwareError)) throw error;
+			return c.json({
+				code: error.code,
+				message: error.message,
+				fix: error.fix
+			}, STATUS[error.code] ?? 500);
+		}
+	};
+}
 /** A weak ETag of a body: the first 128 bits of its SHA-256, in hex. */
 async function etagOf(body) {
 	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(body)));
@@ -2194,19 +2728,8 @@ function installReadApi(app, options) {
 				vary: "Origin",
 				"access-control-allow-origin": new URL(c.env.HOLLWARE_PUBLIC_URL).origin
 			});
-			const answered = await (async () => {
-				try {
-					await next();
-					return c.res;
-				} catch (error) {
-					if (!(error instanceof HollwareError)) throw error;
-					return c.json({
-						code: error.code,
-						message: error.message,
-						fix: error.fix
-					}, STATUS[error.code] ?? 500);
-				}
-			})();
+			await next();
+			const answered = c.res;
 			if (crossOrigin === null) return answered;
 			const shared = new Response(answered.body, answered);
 			shared.headers.set("access-control-allow-origin", crossOrigin);
@@ -2217,8 +2740,18 @@ function installReadApi(app, options) {
 		return c.res;
 	});
 	app.get("/v1/openapi.json", (c) => c.json(openApiDocument()));
-	app.get("/v1/site", async (c) => answer(c, await options.read(c.env).describeSite(c.get("site"))));
-	app.get("/v1/:collection", async (c) => {
+	app.get("/v1/site", readRoute(async (c) => answer(c, await options.read(c.env).describeSite(c.get("site")))));
+	app.get("/v1/search", readRoute(async (c) => {
+		const query = c.req.query();
+		const limit = query["limit"] === void 0 ? void 0 : Number(query["limit"]);
+		return answer(c, await options.read(c.env).search(c.get("site"), query["q"] ?? "", {
+			...query["collection"] === void 0 ? {} : { collection: query["collection"] },
+			...query["locale"] === void 0 ? {} : { locale: query["locale"] },
+			...limit === void 0 ? {} : { limit },
+			...query["mode"] === void 0 ? {} : { mode: searchModeOf(query["mode"]) }
+		}));
+	}));
+	app.get("/v1/:collection", readRoute(async (c) => {
 		const query = c.req.query();
 		const limit = query["limit"] === void 0 ? void 0 : Number(query["limit"]);
 		return answer(c, await options.read(c.env).listEntries(c.get("site"), c.req.param("collection"), {
@@ -2227,12 +2760,27 @@ function installReadApi(app, options) {
 			...limit === void 0 ? {} : { limit },
 			...query["cursor"] === void 0 ? {} : { cursor: query["cursor"] }
 		}));
-	});
-	app.get("/v1/:collection/translations/:group", async (c) => answer(c, await options.read(c.env).getTranslations(c.get("site"), c.req.param("collection"), c.req.param("group"))));
-	app.get("/v1/:collection/:locale/:slug", async (c) => {
+	}));
+	app.get("/v1/:collection/translations/:group", readRoute(async (c) => answer(c, await options.read(c.env).getTranslations(c.get("site"), c.req.param("collection"), c.req.param("group")))));
+	app.get("/v1/:collection/:locale/:slug", readRoute(async (c) => {
 		const formats = c.req.query("formats");
-		return answer(c, await options.read(c.env).getEntry(c.get("site"), c.req.param("collection"), c.req.param("slug"), c.req.param("locale"), formats === void 0 ? {} : { formats: formats.split(",").flatMap((format) => format === "markdown" || format === "document" || format === "html" ? [format] : []) }));
-	});
+		const related = c.req.query("related") === "true" ? { related: true } : {};
+		return answer(c, await options.read(c.env).getEntry(c.get("site"), c.req.param("collection"), c.req.param("slug"), c.req.param("locale"), formats === void 0 ? related : {
+			...related,
+			formats: formats.split(",").flatMap((format) => format === "markdown" || format === "document" || format === "html" ? [format] : [])
+		}));
+	}));
+}
+const SEARCH_MODES = [
+	"fulltext",
+	"semantic",
+	"hybrid"
+];
+/** The `mode` of a search from the query string, or the error that names the ones there are. */
+function searchModeOf(value) {
+	const mode = SEARCH_MODES.find((known) => known === value);
+	if (mode === void 0) throw new HollwareError("invalid_input", `The search mode ${value} is not one Hollware knows.`, `Pass mode as one of ${SEARCH_MODES.join(", ")}, or leave it out for hybrid.`);
+	return mode;
 }
 /** The OpenAPI 3.1 document of the read API. */
 function openApiDocument() {
@@ -2271,6 +2819,20 @@ function openApiDocument() {
 					...common
 				}
 			} },
+			"/v1/search": { get: {
+				operationId: "search",
+				parameters: [
+					param("q", "query", true),
+					param("collection", "query", false),
+					param("locale", "query", false),
+					param("limit", "query", false),
+					param("mode", "query", false)
+				],
+				responses: {
+					"200": ok("The published entries that match q, best first"),
+					...common
+				}
+			} },
 			"/v1/{collection}": { get: {
 				operationId: "list_entries",
 				parameters: [
@@ -2300,7 +2862,8 @@ function openApiDocument() {
 					param("collection", "path", true),
 					param("locale", "path", true),
 					param("slug", "path", true),
-					param("formats", "query", false)
+					param("formats", "query", false),
+					param("related", "query", false)
 				],
 				responses: {
 					"200": ok("A published entry"),
@@ -2495,7 +3058,7 @@ function plainPageHeaders() {
 * The ceremonies, with SimpleWebAuthn and its parsers, in a chunk of their own: only these four
 * routes use them, and a Worker that serves MCP never pays for them at startup (`budgets.json`).
 */
-const ceremonies = () => import("./ceremonies-V_1BbmZQ.mjs");
+const ceremonies = () => import("./ceremonies-6mZ3u32c.mjs");
 /** The cookie of a signed-in person: only `/authorize` reads it (ADR-026). */
 const SESSION_COOKIE = "hollware_session";
 function sessionCookie(secret) {
@@ -2888,6 +3451,66 @@ function build(issuer, options) {
 	};
 }
 //#endregion
+//#region src/http/events.ts
+/** The largest beacon the route reads: a site key and a path, with room to spare. */
+const MAX_BEACON_BYTES = 2048;
+/** The origins whose pages may count views of a site: its own URL and its `cors.origins`. */
+function pageOriginsOf(site) {
+	return [...site.url === null ? [] : [new URL(site.url).origin], ...site.cors.origins];
+}
+function refusal(status, code, message, fix) {
+	return Response.json({
+		code,
+		message,
+		fix
+	}, {
+		status,
+		headers: { "cache-control": "no-store" }
+	});
+}
+/** The path of a view without its query and fragment, or `null` when it is no path. */
+function pathOf(value) {
+	if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//")) return null;
+	const { pathname } = new URL(value, "https://hollware.invalid");
+	return pathname.length > 512 ? null : pathname;
+}
+/**
+* `POST /events`, the beacon of the sites (ADR-031): `{ "site": "<key>", "path": "/<path>" }`, sent
+* by a page with `navigator.sendBeacon`, so with no token. It counts a view of the path when the
+* page is of one of the site's origins (its URL or its `cors.origins`), and keeps the site, the
+* path and the country Cloudflare gives the request: never a cookie, an IP or a user agent. It
+* answers 204 whether or not the Worker has an `ANALYTICS` binding, so that a page cannot tell.
+*/
+function installEvents(app, options) {
+	app.post("/events", async (c) => {
+		const text = await c.req.text();
+		if (new TextEncoder().encode(text).byteLength > 2048) return refusal(413, "too_large", `A beacon is at most ${MAX_BEACON_BYTES} bytes.`, "Send the site and the path of the page, and nothing else.");
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			body = null;
+		}
+		const key = typeof body === "object" && body !== null && "site" in body ? body.site : null;
+		const site = typeof key === "string" ? options.sites.get(key) : void 0;
+		const path = typeof body === "object" && body !== null && "path" in body ? pathOf(body.path) : null;
+		if (site === void 0 || path === null) return refusal(400, "invalid_input", "A beacon is JSON with the key of a site this Hollware serves and the path of a page.", "Send { \"site\": \"<site key>\", \"path\": \"/<path of the page>\" }.");
+		const origin = c.req.header("origin") ?? null;
+		if (origin === null || !pageOriginsOf(site).includes(origin)) return refusal(403, "forbidden_origin", `Only pages of the site "${site.key}" count its views.`, `Set url of the site in hollware.config.ts to the origin of its pages, or add the origin to cors.origins.`);
+		const cf = Reflect.get(c.req.raw, "cf");
+		const country = typeof cf === "object" && cf !== null && "country" in cf && typeof cf.country === "string" ? cf.country : "XX";
+		analyticsWriterOf(c.env)?.record({
+			site: site.key,
+			path,
+			country
+		});
+		return new Response(null, {
+			status: 204,
+			headers: { "cache-control": "no-store" }
+		});
+	});
+}
+//#endregion
 //#region src/http/gateway.ts
 /**
 * A 401 of a resource server, with Hollware's body: the same JSON as every other refusal, and the
@@ -3006,6 +3629,7 @@ function createGateway(options) {
 	*/
 	const readsFromAnyCorsOrigin = (request, origin) => {
 		const { pathname } = new URL(request.url);
+		if (request.method === "POST" && pathname === "/events") return true;
 		return corsOrigins.has(origin) && [
 			"GET",
 			"HEAD",
@@ -3047,7 +3671,9 @@ function createGateway(options) {
 				site,
 				store: createD1Store(db, { clock }),
 				clock,
-				notify: notify(c, requestId, site.key)
+				notify: notify(c, requestId, site.key),
+				semantic: semanticOfEnv(c.env),
+				analytics: analyticsReaderOf(c.env)
 			}
 		});
 	}));
@@ -3090,6 +3716,7 @@ function createGateway(options) {
 		protect: (c, proceed) => protect(c, "v1", proceed),
 		metadataUrl: (c) => oauth(c.env.HOLLWARE_PUBLIC_URL).metadataUrls.v1
 	});
+	installEvents(app, { sites });
 	installErrorHandling(app, log);
 	return async (request, env, ctx) => {
 		contexts.set(request, ctx);
@@ -3278,6 +3905,8 @@ const encoder = new TextEncoder();
 */
 const OUTPUT_TOO_LARGE_FIX = {
 	approve_review: "The operation ran and its change may have been applied: read the review with list_reviews before you repeat it.",
+	comment_review: "The operation ran and its comment may have been added: read the review with list_reviews before you repeat it.",
+	content_stats: "Ask for less: pass a smaller limit.",
 	create_draft: "The operation ran and its change may have been applied: read the entry with get_entry before you repeat it.",
 	describe_site: "The description of the site does not fit in one answer. Document fewer collections, components and contracts, or shorten their descriptions.",
 	get_entry: "Ask for one format at a time with formats: markdown, document or html, instead of several together.",
@@ -3286,6 +3915,8 @@ const OUTPUT_TOO_LARGE_FIX = {
 	list_reviews: "Ask for less: pass a smaller limit.",
 	publish: "The operation ran and its change may have been applied: read the entry with get_entry before you repeat it.",
 	request_changes: "The operation ran and its change may have been applied: read the review with list_reviews before you repeat it.",
+	request_review: "The operation ran and its review may have been asked: read it with list_reviews before you repeat it.",
+	search: "Ask for less: pass a smaller limit.",
 	unpublish: "The operation ran and its change may have been applied: read the entry with get_entry before you repeat it.",
 	update_draft: "The operation ran and its change may have been applied: read the entry with get_entry before you repeat it.",
 	validate: "The verdict lists more problems than fit in one answer. Fix the first ones and validate again."
@@ -3426,6 +4057,33 @@ function createToolTable(operations = OPERATIONS) {
 	});
 }
 //#endregion
+//#region src/mcp/prompts.ts
+/**
+* The prompts of the MCP endpoint: workflows that an agent's user picks by name, written once
+* here. A prompt only says what to do; every step is a tool, checked as any call is.
+*/
+const REFRESH_CONTENT = {
+	name: "refresh_content",
+	title: "Refresh what readers read",
+	description: "Pick a much-read entry whose content has aged, find what the site already says on its subject, and update it through the contracts, ready to publish.",
+	args: z.object({ days: z.string().regex(/^[1-9][0-9]?$/).optional().describe("How many days of reading to look at, 1 to 90; 30 when not given.") })
+};
+/** The text of `refresh_content`: the steps, each with the tool that takes it. */
+function refreshContentText(days) {
+	return [
+		`Refresh the content that readers read most, from the last ${days} days.`,
+		"",
+		`1. Call content_stats with days: ${days}. Pick an entry from the pages with the most views: prefer one whose updatedAt is oldest, or whose subject has moved on. Skip pages with no entry.`,
+		"2. Read it with get_entry, with related: true, and read describe_site for its collection: its schema, contracts and style guide.",
+		"3. Call search with the subject of the entry in your own words (mode hybrid) to find what the site already says, so that the update links to it instead of repeating it.",
+		"4. Write the update: correct what is out of date, add what is missing, link the related entries where they help. Keep the voice of the style guide.",
+		"5. Save it with update_draft at the version you read. Fix every error of the verdict, and the warnings you can, saving again; validate checks a version without saving it.",
+		"6. Call publish. Without content:publish it asks for a review: say so, with the link it answers. With warnings left, say which and why before you acknowledge them.",
+		"",
+		"Report the entry you picked and why, what you changed, and how the publish ended."
+	].join("\n");
+}
+//#endregion
 //#region src/mcp/endpoint.ts
 /**
 * `tools/list` is the same for every client and changes only when the Worker is deployed again:
@@ -3453,15 +4111,6 @@ function authInfoOf(principal, resourceMetadataUrl) {
 	};
 }
 /**
-* Calls the handler of an operation. This is the one place where the typed pairing of specs and
-* handlers meets the dynamic protocol: the SDK parsed `input` with the input schema of `spec`,
-* which is the schema that types the handler of the same name.
-*/
-function invoke(handlers, spec, input, context) {
-	const handler = handlers[spec.name];
-	return handler(input, context);
-}
-/**
 * The MCP endpoint of Hollware: one tool for each operation, served in both protocol eras, for
 * the gateway to mount at `/mcp` after it has checked the Host, the Origin and the token.
 *
@@ -3547,7 +4196,10 @@ function createMcpEndpoint(options) {
 		const call = request.authInfo === void 0 ? void 0 : calls.get(request.authInfo);
 		if (call === void 0) throw new Error("A request reached the MCP server without the call the gateway made for it");
 		const server = new McpServer(options.serverInfo, {
-			capabilities: { tools: { listChanged: false } },
+			capabilities: {
+				tools: { listChanged: false },
+				prompts: { listChanged: false }
+			},
 			cacheHints: { "tools/list": TOOLS_LIST_CACHE_HINT }
 		});
 		for (const tool of tools) server.registerTool(tool.spec.name, {
@@ -3567,6 +4219,17 @@ function createMcpEndpoint(options) {
 				detail: null
 			}))
 		}, (input, mcp) => runTool(tool.spec, input, mcp, call, request.era));
+		server.registerPrompt(REFRESH_CONTENT.name, {
+			title: REFRESH_CONTENT.title,
+			description: REFRESH_CONTENT.description,
+			argsSchema: REFRESH_CONTENT.args
+		}, ({ days }) => ({ messages: [{
+			role: "user",
+			content: {
+				type: "text",
+				text: refreshContentText(days === void 0 ? 30 : Number(days))
+			}
+		}] }));
 		return server;
 	};
 	const handler = createMcpHandler(buildServer, { onerror: (error) => emit({
@@ -3666,7 +4329,8 @@ async function run(deps, env, method, site, schema, build, handler) {
 		store: createD1Store(env.DB.withSession("first-unconstrained")),
 		clock: deps.clock,
 		client: null,
-		requestId
+		requestId,
+		semantic: semanticOfEnv(env)
 	};
 	try {
 		return await handler(input, context);
@@ -3686,7 +4350,7 @@ function createRpc(deps, env) {
 			collection,
 			locale,
 			slug,
-			...readOptions(options, ["formats"])
+			...readOptions(options, ["formats", "related"])
 		}), deps.handlers.get_entry),
 		listEntries: (site, collection, options) => run(deps, env, "listEntries", site, listEntries.input, () => ({
 			collection,
@@ -3701,7 +4365,16 @@ function createRpc(deps, env) {
 			collection,
 			translationGroup
 		}), deps.handlers.get_translations),
-		describeSite: (site) => run(deps, env, "describeSite", site, describeSite.input, () => ({}), deps.handlers.describe_site)
+		describeSite: (site) => run(deps, env, "describeSite", site, describeSite.input, () => ({}), deps.handlers.describe_site),
+		search: (site, query, options) => run(deps, env, "search", site, search.input, () => ({
+			query,
+			...readOptions(options, [
+				"collection",
+				"locale",
+				"limit",
+				"mode"
+			])
+		}), deps.handlers.search)
 	};
 }
 //#endregion
@@ -3730,6 +4403,9 @@ function createEntrypoint(deps) {
 		describeSite(...args) {
 			return createRpc(deps, this.env).describeSite(...args);
 		}
+		search(...args) {
+			return createRpc(deps, this.env).search(...args);
+		}
 	};
 }
 //#endregion
@@ -3813,6 +4489,10 @@ async function runDueSchedules(input) {
 //#endregion
 //#region src/compose.ts
 const systemClock = { now: () => /* @__PURE__ */ new Date() };
+/** Whether the run of the cron at `time` wakes the agents: on the minutes that divide by ten. */
+function wakesAgents(time) {
+	return Math.floor(time / 6e4) % 10 === 0;
+}
 /** What the MCP endpoint calls the server, in `server/discover` and `initialize`. */
 const SERVER_INFO = {
 	name: "hollware",
@@ -3859,7 +4539,8 @@ function createHollwareWith(config, handlers, options = {}) {
 		secret: (name) => {
 			const value = Reflect.get(env, name);
 			return typeof value === "string" ? value : void 0;
-		}
+		},
+		semantic: semanticOfEnv(env)
 	});
 	return {
 		fetch: createGateway({
@@ -3876,7 +4557,7 @@ function createHollwareWith(config, handlers, options = {}) {
 			auth: resolved.auth,
 			handlers
 		}),
-		scheduled: async (_controller, env, ctx) => {
+		scheduled: async (controller, env, ctx) => {
 			const each = async (site) => {
 				await runDueSchedules({
 					site,
@@ -3889,7 +4570,27 @@ function createHollwareWith(config, handlers, options = {}) {
 					queue: env.EVENTS,
 					deps: deliveryDeps(env, site)
 				});
+				const semantic = semanticOfEnv(env);
+				if (semantic !== null) {
+					const now = clock.now().toISOString();
+					await healVectors(connect(env.DB), semantic, {
+						site: site.key,
+						now
+					});
+					await refreshRelated(connect(env.DB), semantic, {
+						site: site.key,
+						now
+					});
+				}
 			};
+			const agents = env.AGENTS;
+			const run = typeof agents === "object" && agents !== null ? Reflect.get(agents, "run") : void 0;
+			if (typeof run === "function" && wakesAgents(controller.scheduledTime)) ctx.waitUntil(Promise.resolve(Reflect.apply(run, agents, [])).catch((error) => {
+				writeLog({
+					kind: "agents_failed",
+					message: String(error)
+				});
+			}));
 			ctx.waitUntil((async () => {
 				for (const site of sites.values()) await each(site).catch((error) => {
 					writeLog({
@@ -3915,53 +4616,6 @@ function createHollwareWith(config, handlers, options = {}) {
 	};
 }
 //#endregion
-//#region src/ops/errors.ts
-/**
-* The error of something that must never happen: a bug of Hollware, not a mistake of the caller.
-* Like the `internal` error of the adapters, its message says nothing about the cause, which goes
-* to the log through `cause`, and its fix names the request id the operator finds the log line by.
-*/
-function internalError(context, cause) {
-	return new HollwareError("internal", "The operation failed on the server.", `Try again. If it keeps failing, give the site operator this request id: ${context.requestId}.`, { cause: new Error(cause) });
-}
-/**
-* The error for an answer of the store that the call it came from can never get: an entry that
-* is created cannot conflict, a publish has no slug to take. It is a bug, not an outcome of the
-* operation, so it is not one of the outcomes of its spec.
-*/
-function unexpectedAnswer(context, call, answer) {
-	return internalError(context, `The store answered ${answer.outcome} to ${call}, which it never does.`);
-}
-//#endregion
-//#region src/ops/actor.ts
-/**
-* Who a write is made by: the person behind the token of the call, with what its client said
-* about itself. A personal token writes as itself (ADR-019); an OAuth access token writes as the
-* client the person allowed, whose id goes with what the client said (ADR-026). The adapters check
-* the scopes of the operation before any handler runs and never route a write for the RPC
-* binding, so reaching one with it is a bug, answered as `internal` before anything is read or
-* written.
-*/
-function actorOf(context) {
-	const { principal } = context;
-	if (principal.kind === "token") return {
-		kind: "token",
-		userId: principal.userId,
-		tokenId: principal.tokenId,
-		meta: context.client
-	};
-	if (principal.kind === "oauth") return {
-		kind: "oauth_client",
-		userId: principal.userId,
-		tokenId: null,
-		meta: {
-			...context.client,
-			oauthClient: principal.clientId
-		}
-	};
-	throw internalError(context, `A write was routed for a principal of kind ${principal.kind}; only a person writes.`);
-}
-//#endregion
 //#region src/ops/answers.ts
 /** A review as an output. */
 function reviewView(review) {
@@ -4062,6 +4716,117 @@ function publicationView(publication) {
 		at: publication.createdAt
 	};
 }
+/** A comment on a review as the operations answer it; `client` is the name its client gave. */
+function reviewCommentView(comment) {
+	const name = comment.authorMeta?.["name"];
+	return {
+		id: comment.id,
+		author: comment.authorId,
+		authorName: comment.authorName,
+		client: typeof name === "string" ? name : null,
+		body: comment.body,
+		at: comment.createdAt
+	};
+}
+//#endregion
+//#region src/ops/content-stats.ts
+/** A path without its trailing slash, so that `/blog/a` and `/blog/a/` are one page. */
+function trimmed(path) {
+	return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+/**
+* The entry that a path of the site shows, by the routes of its collections: the slug is the part
+* of the path where the route has `:slug`. `null` for a path that no route has.
+*/
+function entryRefOf(site, path) {
+	const wanted = trimmed(path);
+	for (const [collection, resolved] of site.collections) for (const [locale, route] of Object.entries(resolved.routes)) {
+		const [before, after, ...rest] = trimmed(route).split(":slug");
+		if (before === void 0 || after === void 0 || rest.length > 0) continue;
+		if (!wanted.startsWith(before) || !wanted.endsWith(after)) continue;
+		const slug = wanted.slice(before.length, wanted.length - after.length);
+		if (slug !== "" && !slug.includes("/")) return {
+			collection,
+			locale,
+			slug
+		};
+	}
+	return null;
+}
+/**
+* The most read pages of the site, from the counts of its beacons (ADR-031), each with the
+* published entry it shows. `unavailable` when the deployment cannot read the counts.
+*/
+const contentStats = async (input, context) => {
+	const analytics = context.analytics ?? null;
+	if (analytics === null) return { outcome: "unavailable" };
+	const site = context.site;
+	const counts = await analytics.topPages(site.key, {
+		days: input.days,
+		limit: input.limit
+	});
+	const pages = await Promise.all(counts.map(async (count) => {
+		const ref = entryRefOf(site, count.path);
+		const found = ref === null ? null : await context.store.findEntry(site.key, ref, "published");
+		return {
+			path: count.path,
+			views: count.views,
+			entry: found === null ? null : entrySummary(found)
+		};
+	}));
+	return {
+		outcome: "ok",
+		since: (/* @__PURE__ */ new Date(context.clock.now().getTime() - input.days * 864e5)).toISOString(),
+		pages
+	};
+};
+//#endregion
+//#region src/ops/errors.ts
+/**
+* The error of something that must never happen: a bug of Hollware, not a mistake of the caller.
+* Like the `internal` error of the adapters, its message says nothing about the cause, which goes
+* to the log through `cause`, and its fix names the request id the operator finds the log line by.
+*/
+function internalError(context, cause) {
+	return new HollwareError("internal", "The operation failed on the server.", `Try again. If it keeps failing, give the site operator this request id: ${context.requestId}.`, { cause: new Error(cause) });
+}
+/**
+* The error for an answer of the store that the call it came from can never get: an entry that
+* is created cannot conflict, a publish has no slug to take. It is a bug, not an outcome of the
+* operation, so it is not one of the outcomes of its spec.
+*/
+function unexpectedAnswer(context, call, answer) {
+	return internalError(context, `The store answered ${answer.outcome} to ${call}, which it never does.`);
+}
+//#endregion
+//#region src/ops/actor.ts
+/**
+* Who a write is made by: the person behind the token of the call, with what its client said
+* about itself. A personal token writes as itself (ADR-019); an OAuth access token writes as the
+* client the person allowed, whose id goes with what the client said (ADR-026). The adapters check
+* the scopes of the operation before any handler runs and never route a write for the RPC
+* binding, so reaching one with it is a bug, answered as `internal` before anything is read or
+* written.
+*/
+function actorOf(context) {
+	const { principal } = context;
+	if (principal.kind === "token") return {
+		kind: "token",
+		userId: principal.userId,
+		tokenId: principal.tokenId,
+		meta: context.client
+	};
+	if (principal.kind === "oauth") return {
+		kind: "oauth_client",
+		userId: principal.userId,
+		tokenId: null,
+		meta: {
+			...context.client,
+			oauthClient: principal.clientId
+		}
+	};
+	throw internalError(context, `A write was routed for a principal of kind ${principal.kind}; only a person writes.`);
+}
 //#endregion
 //#region src/ops/collections.ts
 /**
@@ -4261,6 +5026,7 @@ const getEntry$1 = async (input, context) => {
 	if (found === null) return { outcome: "not_found" };
 	const { entry, revision } = found;
 	const publication = await context.store.lastPublication(context.site.key, entry.id);
+	const related = input.related ? await relatedEntries(context, entry.id) : void 0;
 	return {
 		outcome: "ok",
 		entry: {
@@ -4271,9 +5037,19 @@ const getEntry$1 = async (input, context) => {
 			...input.formats.includes("markdown") ? { markdown: revision.markdown } : {},
 			...input.formats.includes("document") ? { document: revision.document } : {},
 			...input.formats.includes("html") ? { html: await renderHtml(revision.document) } : {}
-		}
+		},
+		...related === void 0 ? {} : { related }
 	};
 };
+/**
+* The published entries closest to one, as its vectors found them when it was indexed: none when
+* the deployment has no semantic search, and none that is no longer published.
+*/
+async function relatedEntries(context, entryId) {
+	if ((context.semantic ?? null) === null) return [];
+	const related = await context.store.relatedOf(context.site.key, entryId);
+	return (await context.store.findSummaries(context.site.key, related.map((item) => item.id), "published")).map(entrySummary);
+}
 //#endregion
 //#region src/ops/get-translations.ts
 /** Reads the entries of a translation group in the view of the call, one per locale. */
@@ -4308,6 +5084,93 @@ const listEntries$1 = async (input, context) => {
 		nextCursor: page.nextCursor
 	};
 };
+/** The published entries closest to the meaning of the query, closest first. */
+async function semanticSearch(semantic, store, site, query) {
+	const [vector] = await semantic.embedder.embed([query.text]);
+	const matches = await semantic.index.query(vector ?? [], {
+		topK: 20,
+		site,
+		...query.collection === void 0 ? {} : { collection: query.collection },
+		...query.locale === void 0 ? {} : { locale: query.locale }
+	});
+	const best = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		const kept = best.get(match.metadata.entry);
+		if (kept === void 0 || match.score > kept.score) best.set(match.metadata.entry, match);
+	}
+	const ranked = [...best.values()].sort((a, b) => b.score - a.score).slice(0, query.limit);
+	const summaries = await store.findSummaries(site, ranked.map((match) => match.metadata.entry), "published");
+	const byId = new Map(summaries.map((summary) => [summary.entry.id, summary]));
+	return ranked.flatMap((match) => {
+		const entry = byId.get(match.metadata.entry);
+		return entry === void 0 ? [] : [{
+			entry,
+			snippet: match.metadata.excerpt,
+			score: match.score
+		}];
+	});
+}
+/**
+* Merges rankings by reciprocal rank fusion: an entry scores `1 / (FUSION_K + place)` in each list
+* it is in, places counted from 1. An entry keeps the snippet of the first list that has it, so
+* the words found by full text win over the excerpt of a match by meaning.
+*/
+function fuse(lists, limit) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const list of lists) list.forEach((hit, place) => {
+		const gain = 1 / (60 + place + 1);
+		const kept = merged.get(hit.entry.entry.id);
+		merged.set(hit.entry.entry.id, kept === void 0 ? {
+			...hit,
+			score: gain
+		} : {
+			...kept,
+			score: kept.score + gain
+		});
+	});
+	return [...merged.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+}
+//#endregion
+//#region src/ops/search.ts
+/**
+* The published entries of the site that match the query, best first: by its words, by meaning,
+* or both (ADR-030). Without the semantic search of the deployment, every mode is full text, and
+* the answer's `mode` says which one ran.
+*/
+const search$1 = async (input, context) => {
+	if (input.collection !== void 0) requireCollection(context.site, input.collection);
+	if (input.locale !== void 0) requireLocale(context.site, input.locale);
+	const query = {
+		text: input.query,
+		collection: input.collection,
+		locale: input.locale,
+		limit: input.limit
+	};
+	const semantic = context.semantic ?? null;
+	const asked = input.mode ?? "hybrid";
+	const mode = semantic === null ? "fulltext" : asked;
+	const site = context.site.key;
+	let hits;
+	if (semantic === null || mode === "fulltext") hits = await context.store.searchEntries(site, query);
+	else if (mode === "semantic") hits = await semanticSearch(semantic, context.store, site, query);
+	else {
+		const wide = {
+			...query,
+			limit: Math.max(query.limit, 20)
+		};
+		const [words, meaning] = await Promise.all([context.store.searchEntries(site, wide), semanticSearch(semantic, context.store, site, wide)]);
+		hits = fuse([words, meaning], query.limit);
+	}
+	return {
+		outcome: "ok",
+		mode,
+		results: hits.map((hit) => ({
+			entry: entrySummary(hit.entry),
+			snippet: hit.snippet,
+			score: hit.score
+		}))
+	};
+};
 //#endregion
 //#region src/ops/event.ts
 /** The path of an entry: the route of its locale, with its slug in place of `:slug`. */
@@ -4625,13 +5488,15 @@ const listReviews = async (input, context) => {
 		status: input.status,
 		limit: input.limit
 	});
+	const comments = await context.store.reviewComments(context.site.key, found.map((review) => review.id));
 	const reviews = [];
 	for (const review of found) {
 		const view = await context.store.findEntryById(context.site.key, review.entryId, "head");
 		if (view === null) throw unexpectedAnswer(context, "list_reviews", { outcome: "no entry" });
 		reviews.push({
 			...reviewView(review),
-			entry: entrySummary(view)
+			entry: entrySummary(view),
+			comments: (comments.get(review.id) ?? []).map(reviewCommentView)
 		});
 	}
 	return {
@@ -4697,6 +5562,56 @@ const requestChanges = async (input, context) => {
 		review: reviewView(closed.review)
 	};
 };
+/**
+* A comment on a pending review, in the name of the caller: for the person who decides and for
+* the author. It decides nothing; a review that is no longer pending takes none.
+*/
+const commentReview = async (input, context) => {
+	const answer = await context.store.commentReview(context.site.key, {
+		reviewId: input.id,
+		actor: actorOf(context),
+		body: input.body
+	});
+	return answer.outcome === "commented" ? {
+		outcome: "commented",
+		comment: reviewCommentView(answer.comment)
+	} : { outcome: answer.outcome };
+};
+/**
+* Asks for a review of the head revision of an entry through `publish`, with `content:publish`
+* taken from the caller for this call: the same checks run, and the one thing that cannot happen
+* is a publication. It is how an agent sends its work to a person, whatever its token holds.
+*/
+const requestReview = async (input, context) => {
+	const { principal: given } = context;
+	const principal = given.kind === "binding" ? given : {
+		...given,
+		scopes: given.scopes.filter((scope) => scope !== "content:publish")
+	};
+	const answer = await publish$1({
+		id: input.id,
+		version: input.version,
+		acknowledgeWarnings: input.acknowledgeWarnings,
+		group: []
+	}, {
+		...context,
+		principal
+	});
+	switch (answer.outcome) {
+		case "pending_review":
+		case "blocked":
+		case "needs_acknowledgement":
+		case "conflict":
+		case "not_found": return {
+			outcome: answer.outcome,
+			...answer.entry === void 0 ? {} : { entry: answer.entry },
+			...answer.verdict === void 0 ? {} : { verdict: answer.verdict },
+			...answer.conflict === void 0 ? {} : { conflict: answer.conflict },
+			...answer.review === void 0 ? {} : { review: answer.review }
+		};
+		default: throw unexpectedAnswer(context, "request_review", answer);
+	}
+};
 //#endregion
 //#region src/ops/unpublish.ts
 /**
@@ -4842,14 +5757,18 @@ function defineHandlers(handlers) {
 */
 const handlers = defineHandlers({
 	approve_review: approveReview,
+	comment_review: commentReview,
+	content_stats: contentStats,
 	create_draft: createDraft,
 	describe_site: describeSite$1,
 	get_entry: getEntry$1,
 	get_translations: getTranslations$1,
 	list_entries: listEntries$1,
+	search: search$1,
 	list_reviews: listReviews,
 	publish: publish$1,
 	request_changes: requestChanges,
+	request_review: requestReview,
 	unpublish,
 	update_draft: updateDraft,
 	validate