@mnmal-ai/substrate-nl 0.0.0-stage → 1.0.0-alpha.0

package/dist/bootstrap-BpKUloR3.js

@@ -0,0 +1,1821 @@
+import { defineBootstrap, error400, jsonResponse, parseJsonBody } from "@mnmal-ai/substrate/sdk";
+import { z } from "zod";
+import { createHash } from "node:crypto";
+
+//#region src/own.ts
+/**
+* A lookup into a plain-object record by a user-supplied key. Inherited
+* names (`constructor`, `__proto__`, `toString`) are not entries.
+*/
+function own(rec, key) {
+	return rec !== void 0 && Object.hasOwn(rec, key) ? rec[key] : void 0;
+}
+
+//#endregion
+//#region src/pack/words.ts
+/** `AgentMessage` -> ['agent', 'message']; `shortId` -> ['short', 'id']. */
+function splitWords(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[\s_-]+/).filter((w) => w.length > 0);
+}
+/** English plural for a lower-case noun, by suffix rule. */
+function pluralize(word) {
+	if (/(s|x|z|ch|sh)$/.test(word)) return `${word}es`;
+	if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
+	return `${word}s`;
+}
+/** Sorted, de-duplicated. */
+function uniqueSorted(xs) {
+	return [...new Set(xs)].sort();
+}
+
+//#endregion
+//#region src/parse/time.ts
+const WEEKDAYS = [
+	"sunday",
+	"monday",
+	"tuesday",
+	"wednesday",
+	"thursday",
+	"friday",
+	"saturday"
+];
+/**
+* The range a time phrase names, relative to `asOf` and in its offset:
+* today, yesterday, this/last week (weeks start Monday), this/last month,
+* rolling "past <unit>" and "last N <units>", "since <weekday>". Null when
+* the phrase is not a time phrase.
+*/
+function rangeFor(phrase, asOf) {
+	const m = /^(\d{4})-(\d{2})-(\d{2})T[\d:.]+(Z|[+-]\d{2}:\d{2})$/.exec(asOf);
+	if (m === null) throw new Error(`asOf must be ISO-8601 with an offset: ${asOf}`);
+	const [, y, mo, d, offset] = m;
+	const today = Date.UTC(Number(y), Number(mo) - 1, Number(d));
+	const day = 864e5;
+	const at = (utcMidnight) => `${new Date(utcMidnight).toISOString().slice(0, 10)}T00:00:00${offset === "Z" ? "Z" : offset}`;
+	const weekday = new Date(today).getUTCDay();
+	const monday = today - (weekday + 6) % 7 * day;
+	const monthStart = Date.UTC(Number(y), Number(mo) - 1, 1);
+	const nextMonth = Date.UTC(Number(y), Number(mo), 1);
+	const lastMonth = Date.UTC(Number(y), Number(mo) - 2, 1);
+	switch (phrase) {
+		case "today": return {
+			gte: at(today),
+			lt: at(today + day)
+		};
+		case "yesterday": return {
+			gte: at(today - day),
+			lt: at(today)
+		};
+		case "this week": return {
+			gte: at(monday),
+			lt: at(monday + 7 * day)
+		};
+		case "last week": return {
+			gte: at(monday - 7 * day),
+			lt: at(monday)
+		};
+		case "this month": return {
+			gte: at(monthStart),
+			lt: at(nextMonth)
+		};
+		case "last month": return {
+			gte: at(lastMonth),
+			lt: at(monthStart)
+		};
+	}
+	const rolling = /^(?:past|last) (\d+ )?(day|week|month|year)s?$/.exec(phrase);
+	if (rolling !== null && (rolling[1] !== void 0 || phrase.startsWith("past"))) {
+		const n = rolling[1] === void 0 ? 1 : Number(rolling[1]);
+		const unit = rolling[2];
+		const back = new Date(today);
+		if (unit === "day") back.setUTCDate(back.getUTCDate() - n);
+		if (unit === "week") back.setUTCDate(back.getUTCDate() - 7 * n);
+		if (unit === "month") back.setUTCMonth(back.getUTCMonth() - n);
+		if (unit === "year") back.setUTCFullYear(back.getUTCFullYear() - n);
+		return {
+			gte: at(back.getTime()),
+			lt: at(today + day)
+		};
+	}
+	const since = /^since (\w+)$/.exec(phrase);
+	if (since !== null) {
+		const target = WEEKDAYS.indexOf(since[1]);
+		if (target < 0) return null;
+		return {
+			gte: at(today - (weekday - target + 7) % 7 * day),
+			lt: at(today + day)
+		};
+	}
+	return null;
+}
+
+//#endregion
+//#region src/parse/parse.ts
+/** Words that carry no query meaning on their own. */
+const GLUE = new Set("a about again all am an and any anything are as at be been by can could current did do does for from get give go got have hey i i'm in is it it's let let's lets list me more my need needs next now of ok on or our please raised see show so some still talk tell that the their them there these this those to us want was we we've we'd what what's whats when where which who whose why will with would you your yo up thought handled judgement judgment make nice there's anymore stuff things few runs run lives wrote write written created made filed logged".split(/\s+/));
+/** First word of an imperative edit, which substrate-nl refuses: it only reads. */
+const MUTATIONS = new Set("close delete remove archive merge approve approved create add update set mark rename reopen assign ack deploy cut land".split(" "));
+const LEADING_FILLER = new Set("please can could would you go ahead let let's lets hey ok yo so and then".split(" "));
+const STATE_CUES = new Set("what what's whats show talk tell status is describe about see which who".split(" "));
+const CLOSE_VERBS = new Set("close closed closing done finished completed resolved ship shipped drop dropped cancel cancelled abandoned".split(" "));
+const UPDATE_VERBS = new Set("updated changed edited touched".split(" "));
+/** Terminal status values: matching one is a question about the past. */
+const TERMINAL = [
+	"closed",
+	"complete",
+	"completed",
+	"done",
+	"resolved",
+	"superseded"
+];
+/** Terminal statuses a closing verb selects: finished, not merely replaced. */
+const CLOSED = [
+	"closed",
+	"complete",
+	"completed",
+	"done",
+	"resolved"
+];
+const HISTORY_WORDS = new Set("archived archive history historical ever previously past trend trends over-time all-time total".split(" "));
+const LATEST = new Set("latest newest recent last".split(" "));
+const OLDEST = new Set("oldest earliest first".split(" "));
+const AUTHOR_VERBS = new Set("raised created written filed authored opened made sent logged".split(" "));
+const BUILTIN_FIELD_ALIASES = { author: "createdById" };
+/** `field:value`, `field:[a,b]`, `field:"two words"`; optionally wrapped in quotes. A clock time starts with a digit. */
+const CLAUSE = /(['"]?)\b([A-Za-z][A-Za-z0-9]*):(\[[^\]]*\]|"[^"]*"|[^\s,'"]+)\1/g;
+function parseClause(span, field, raw) {
+	const unquote = (v) => v.trim().replace(/^["']|["']$/g, "");
+	if (raw.startsWith("[")) return {
+		span,
+		field,
+		op: "in",
+		values: raw.slice(1, -1).split(",").map(unquote).filter((v) => v.length > 0)
+	};
+	if (raw.startsWith("\"")) return {
+		span,
+		field,
+		op: "eq",
+		values: [unquote(raw)]
+	};
+	const cmp = /^(>=|<=|>|<)(.+)$/.exec(raw);
+	if (cmp !== null) return {
+		span,
+		field,
+		op: {
+			">": "gt",
+			">=": "gte",
+			"<": "lt",
+			"<=": "lte"
+		}[cmp[1]],
+		values: [cmp[2]]
+	};
+	const range = /^(.+)\.\.(.+)$/.exec(raw);
+	if (range !== null) return {
+		span,
+		field,
+		op: "between",
+		values: [range[1], range[2]]
+	};
+	if (raw.startsWith("!")) return {
+		span,
+		field,
+		op: "neq",
+		values: [raw.slice(1)]
+	};
+	if (raw.startsWith("~")) return {
+		span,
+		field,
+		op: "contains",
+		values: [raw.slice(1)]
+	};
+	return {
+		span,
+		field,
+		op: "eq",
+		values: [raw]
+	};
+}
+function parseQuestion(question, pack, ctx) {
+	const rulings = ctx.rulings ?? {};
+	const clauses = [];
+	const tokens = (question.replace(CLAUSE, (span, _q, field, raw) => {
+		clauses.push(parseClause(span, field, raw));
+		return " ";
+	}).toLowerCase().replace(/[‘’]/g, "'").match(/#\d+|[a-z0-9@[][a-z0-9@._'\]-]*/g) ?? []).map((t) => t.replace(/[.'-]+$/, "").replace(/'s$/, "")).filter((t) => t.length > 0).map((text) => ({
+		text,
+		used: false
+	}));
+	const words = tokens.map((t) => t.text);
+	const evidence = [];
+	const lead = words.find((w) => !LEADING_FILLER.has(w));
+	if (lead !== void 0 && MUTATIONS.has(lead)) return {
+		status: "refuse",
+		candidates: [],
+		residual: [],
+		reason: `"${lead}" is an edit; substrate-nl answers questions and does not change data`
+	};
+	const values = [];
+	claimNgrams(tokens, 4, (key, at) => {
+		const alias = own(rulings.valueAliases, key);
+		if (alias === void 0) return false;
+		values.push({
+			span: key,
+			key: null,
+			alias,
+			at
+		});
+		return true;
+	});
+	const mentioned = /* @__PURE__ */ new Map();
+	for (const entry of buildTypeIndex(pack, rulings)) {
+		const n = entry.phrase.split(" ").length;
+		for (let i = 0; i + n <= tokens.length; i++) {
+			const slice = tokens.slice(i, i + n);
+			if (slice.some((t) => t.used) || slice.map((t) => t.text).join(" ") !== entry.phrase) continue;
+			for (const t of slice) t.used = true;
+			for (const type of entry.types) mentioned.set(type, {
+				span: entry.phrase,
+				plural: entry.plural
+			});
+		}
+	}
+	for (const [type, m] of mentioned) evidence.push({
+		span: m.span,
+		role: "type",
+		detail: type
+	});
+	const time = claimTime(tokens, ctx.asOf);
+	if (time !== null) evidence.push({
+		span: time.span,
+		role: "time",
+		detail: `${time.range.gte} .. ${time.range.lt}`
+	});
+	const ids = [];
+	let bareNumber = false;
+	tokens.forEach((t, i) => {
+		if (t.used) return;
+		if (/^#\d+$/.test(t.text)) {
+			ids.push(Number(t.text.slice(1)));
+			t.used = true;
+			evidence.push({
+				span: t.text,
+				role: "id",
+				detail: "shortId"
+			});
+		} else if (/^\d+$/.test(t.text)) {
+			if (tokens[i - 1]?.used === true && mentioned.size > 0) {
+				ids.push(Number(t.text));
+				t.used = true;
+				evidence.push({
+					span: t.text,
+					role: "id",
+					detail: "shortId"
+				});
+			} else bareNumber = true;
+		}
+	});
+	let order = null;
+	let count = false;
+	let allProjects = false;
+	let historyWord = false;
+	const singularMention = [...mentioned.values()].some((m) => !m.plural);
+	tokens.forEach((t, i) => {
+		if (t.used) return;
+		const next = tokens[i + 1];
+		if (LATEST.has(t.text) || t.text === "most" && /^recent(ly)?$/.test(next?.text ?? "") || t.text === "current" && singularMention) {
+			order = "desc";
+			t.used = true;
+			if (t.text === "most" && next !== void 0) next.used = true;
+			evidence.push({
+				span: t.text,
+				role: "order",
+				detail: "createdAt desc, limit 1"
+			});
+		} else if (OLDEST.has(t.text)) {
+			order = "asc";
+			t.used = true;
+			evidence.push({
+				span: t.text,
+				role: "order",
+				detail: "createdAt asc, limit 1"
+			});
+		} else if (t.text === "how" && next?.text === "many") {
+			count = true;
+			t.used = true;
+			next.used = true;
+			evidence.push({
+				span: "how many",
+				role: "count",
+				detail: "answer = count"
+			});
+		} else if ((t.text === "every" || t.text === "all") && /^projects?$/.test(next?.text ?? "")) {
+			allProjects = true;
+			t.used = true;
+			next.used = true;
+			evidence.push({
+				span: `${t.text} ${next?.text}`,
+				role: "scope",
+				detail: "no project scope"
+			});
+		} else if (t.text === "across") {
+			allProjects = true;
+			t.used = true;
+		} else if (HISTORY_WORDS.has(t.text)) {
+			historyWord = true;
+			t.used = true;
+			evidence.push({
+				span: t.text,
+				role: "history",
+				detail: "search the whole record"
+			});
+		}
+	});
+	let author = null;
+	tokens.forEach((t, i) => {
+		const prev = tokens[i - 1];
+		const next = tokens[i + 1];
+		if (t.text === "by" && prev !== void 0 && AUTHOR_VERBS.has(prev.text) && next !== void 0) {
+			author = next.text;
+			for (const x of [
+				prev,
+				t,
+				next
+			]) x.used = true;
+		} else if (t.text === "sent" && prev !== void 0 && !GLUE.has(prev.text) && !prev.used) {
+			author = prev.text;
+			prev.used = true;
+			t.used = true;
+		}
+	});
+	if (author !== null) evidence.push({
+		span: author,
+		role: "author",
+		detail: `createdById startsWith ${author}`
+	});
+	const fieldAliases = {
+		...BUILTIN_FIELD_ALIASES,
+		...rulings.fieldAliases ?? {}
+	};
+	let askField = null;
+	tokens.forEach((t, i) => {
+		if (t.used || tokens[i - 1]?.text !== "which") return;
+		for (const form of [t.text, t.text.replace(/s$/, "")]) {
+			const field = own(fieldAliases, form) ?? (fieldNamed(pack, form) ? form : null);
+			if (field === null) continue;
+			askField = {
+				field,
+				group: form !== t.text
+			};
+			t.used = true;
+			evidence.push({
+				span: t.text,
+				role: "field",
+				detail: askField.group ? `group by ${field}` : `answer = ${field}`
+			});
+			return;
+		}
+	});
+	const flagClaims = /* @__PURE__ */ new Map();
+	for (const type of mentioned.keys()) for (const [name, f] of Object.entries(own(pack.types, type)?.fields ?? {})) {
+		if (f.valueType !== "boolean" || name === "archived") continue;
+		const t = tokens.find((x) => !x.used && f.phrases.includes(x.text));
+		if (t === void 0) continue;
+		t.used = true;
+		flagClaims.set(type, [...flagClaims.get(type) ?? [], {
+			span: t.text,
+			role: "value",
+			detail: name
+		}]);
+	}
+	claimNgrams(tokens, 4, (key, at) => {
+		if (at.length === 1 && GLUE.has(key)) return false;
+		if (at.length === 1 && CLOSE_VERBS.has(key)) return false;
+		const found = own(pack.values, key) !== void 0 ? key : at.length === 1 && /[^s]s$/.test(key) && own(pack.values, key.slice(0, -1)) !== void 0 ? key.slice(0, -1) : null;
+		if (found === null) return false;
+		values.push({
+			span: key,
+			key: found,
+			at
+		});
+		return true;
+	});
+	const closeVerb = words.some((w) => CLOSE_VERBS.has(w));
+	const updateVerb = words.some((w) => UPDATE_VERBS.has(w));
+	for (const t of tokens) if (CLOSE_VERBS.has(t.text) || UPDATE_VERBS.has(t.text)) t.used = true;
+	let types = [...mentioned.keys()].sort();
+	if (ctx.forceType !== void 0 && own(pack.types, ctx.forceType) !== void 0) {
+		types = [ctx.forceType];
+		if (!mentioned.has(ctx.forceType)) evidence.push({
+			span: "",
+			role: "type",
+			detail: ctx.forceType
+		});
+	}
+	if (types.length === 0 && ids.length > 0 && ctx.defaultIdType !== void 0) types = [ctx.defaultIdType];
+	if (types.length === 0 && values.length > 0) {
+		types = typesCovering(pack, values);
+		const live = types.filter((t) => values.some((v) => v.key !== null && v.key === own(rulings.liveStatus, t)));
+		if (types.length > 1 && live.length > 0) types = live;
+	}
+	if (types.length === 0 && clauses.length > 0) types = typesWithFields(pack, clauses, rulings);
+	if (types.length === 0 && closeVerb) types = closableTypes(pack);
+	const named = mentioned.size > 0 || ctx.forceType !== void 0;
+	if (bareNumber && ids.length === 0 && !named) return {
+		status: "clarify",
+		candidates: [],
+		residual: [],
+		reason: "a bare number with no type"
+	};
+	if (ids.length > 0 && !named && !words.some((w) => STATE_CUES.has(w))) return {
+		status: "clarify",
+		candidates: [],
+		residual: [],
+		reason: "#N with no question about it: a Todo or a PR?"
+	};
+	if (types.length === 0) return {
+		status: "unparsed",
+		candidates: [],
+		evidence,
+		residual: contentWords(tokens),
+		reason: "no type, id or known value"
+	};
+	const candidates = [];
+	const ruledOut = [];
+	for (const type of types) {
+		const c = assemble(type, {
+			pack,
+			ctx,
+			tokens: tokens.map((t) => ({ ...t })),
+			evidence: evidence.filter((e) => e.role !== "type" || e.detail === type),
+			ids,
+			values,
+			clauses,
+			time,
+			order,
+			count,
+			allProjects,
+			historyWord,
+			flags: flagClaims.get(type) ?? [],
+			author,
+			askField,
+			closeVerb,
+			updateVerb
+		});
+		if ("reason" in c) ruledOut.push(`${type}: ${c.reason}`);
+		else candidates.push(c);
+	}
+	if (candidates.length === 0) {
+		const reason = ruledOut.length > 0 ? ruledOut.join("; ") : "no type fits every value";
+		return {
+			status: "unparsed",
+			candidates,
+			evidence,
+			residual: contentWords(tokens),
+			reason
+		};
+	}
+	if (candidates.length > 1) return {
+		status: "ambiguous",
+		candidates,
+		residual: [],
+		reason: `${candidates.length} readings`
+	};
+	const only = candidates[0];
+	if (only.residual.length > 0 && ids.length === 0) return {
+		status: "partial",
+		candidates,
+		residual: only.residual,
+		reason: `unexplained: ${only.residual.join(", ")}`
+	};
+	return {
+		status: "resolved",
+		candidates,
+		residual: only.residual
+	};
+}
+/** One reading of the question as `type`, or why there is none. */
+function assemble(type, a) {
+	const { pack, ctx, tokens } = a;
+	const rulings = ctx.rulings ?? {};
+	const fields = own(pack.types, type)?.fields ?? {};
+	const words = tokens.map((t) => t.text);
+	const ev = [...a.evidence];
+	const where = [];
+	if (a.ids.length > 0) where.push({ shortId: a.ids.length === 1 ? { eq: a.ids[0] } : { in: a.ids } });
+	const byField = /* @__PURE__ */ new Map();
+	const usedFields = /* @__PURE__ */ new Set();
+	let terminal = false;
+	for (const v of a.ids.length > 0 ? [] : a.values) {
+		if (v.alias !== void 0) {
+			const hit = v.alias.find((x) => x.type === type);
+			if (hit === void 0) return { reason: `"${v.span}" does not apply to ${type}` };
+			const op = hit.in !== void 0 ? { in: hit.in } : hit.eq !== void 0 ? { eq: hit.eq } : hit.startsWith !== void 0 ? { startsWith: hit.startsWith } : { contains: hit.contains };
+			where.push({ [hit.field]: op });
+			usedFields.add(hit.field);
+			ev.push({
+				span: v.span,
+				role: "value",
+				detail: `${hit.field} ${JSON.stringify(op)}`
+			});
+			continue;
+		}
+		const refs = (own(a.pack.values, v.key) ?? []).filter((r) => r.type === type);
+		if (refs.length === 0) return { reason: `"${v.span}" is not a ${type} value` };
+		const field = pickField(refs.map((r) => r.field), fields, words);
+		const stored = refs.find((r) => r.field === field)?.value ?? v.key;
+		if (TERMINAL.includes(stored)) terminal = true;
+		byField.set(field, [...byField.get(field) ?? [], stored]);
+		usedFields.add(field);
+		ev.push({
+			span: v.span,
+			role: "value",
+			detail: `${field} = ${stored}`
+		});
+	}
+	for (const [field, vals] of [...byField].sort(([x], [y]) => x.localeCompare(y))) if (fields[field]?.kind === "list") for (const v of vals) where.push({ [field]: { has: v } });
+	else where.push({ [field]: vals.length === 1 ? { eq: vals[0] } : { in: vals } });
+	for (const c of a.clauses) {
+		const name = resolveField(c.field, fields, rulings);
+		const f = name === null ? void 0 : fields[name];
+		if (name === null || f === void 0) return { reason: `${type} has no field "${c.field}"` };
+		if (!f.operators.includes(c.op)) return { reason: `${name} does not accept ${c.op}` };
+		const coerced = c.values.map((v) => coerce(v, f));
+		if (coerced.some((v) => v === void 0)) return { reason: `"${c.span}" is not a ${f.valueType} value` };
+		const operand = c.op === "in" || c.op === "between" ? coerced : coerced[0];
+		where.push({ [name]: { [c.op]: operand } });
+		usedFields.add(name);
+		ev.push({
+			span: c.span,
+			role: "value",
+			detail: `${name} ${c.op} ${JSON.stringify(operand)} (inline)`
+		});
+	}
+	for (const field of usedFields) creditFieldWords(tokens, fields[field]);
+	if (a.author !== null) where.push({ createdById: { startsWith: a.author } });
+	for (const flag of a.flags) {
+		usedFields.add(flag.detail);
+		where.push({ [flag.detail]: { eq: true } });
+		ev.push({
+			...flag,
+			detail: `${flag.detail} = true`
+		});
+	}
+	for (const [name, f] of Object.entries(fields)) {
+		if (f.valueType !== "boolean" || name === "archived" || usedFields.has(name)) continue;
+		const t = tokens.find((x) => !x.used && f.phrases.includes(x.text));
+		if (t === void 0) continue;
+		t.used = true;
+		usedFields.add(name);
+		where.push({ [name]: { eq: true } });
+		ev.push({
+			span: t.text,
+			role: "value",
+			detail: `${name} = true`
+		});
+	}
+	const historical = a.historyWord || a.time !== null || a.closeVerb || terminal;
+	if (a.time !== null) {
+		const dateField = Object.entries(fields).find(([, f]) => f.valueType === "date" && f.kind !== "metadata" && creditFieldWords(tokens, f))?.[0] ?? (a.closeVerb || a.updateVerb ? "updatedAt" : own(rulings.timeField, type) ?? "createdAt");
+		where.push({ [dateField]: {
+			gte: a.time.range.gte,
+			lt: a.time.range.lt
+		} });
+	}
+	if (a.ids.length === 0) {
+		const statusField = fields.status;
+		const live = own(rulings.liveStatus, type);
+		if (a.closeVerb && statusField?.enum !== void 0 && !byField.has("status")) {
+			const closed = statusField.enum.filter((s) => CLOSED.includes(s));
+			if (closed.length > 0) where.push({ status: { in: closed } });
+		} else if (!historical && live !== void 0 && statusField?.enum?.includes(live) === true && !usedFields.has("status") && a.order === null) where.push({ status: { eq: live } });
+		if (!historical && fields.archived !== void 0) where.push({ archived: { eq: false } });
+		else if (historical) ev.push({
+			span: "(history)",
+			role: "history",
+			detail: "archived rows included"
+		});
+		if (fields.active?.valueType === "boolean" && !usedFields.has("active") && !words.includes("inactive")) where.push({ active: { eq: true } });
+		const scoped = fields.project !== void 0 && !(rulings.unscopedTypes ?? []).includes(type);
+		const groupedByProject = a.askField?.group === true && a.askField.field === "project";
+		if (scoped && !usedFields.has("project") && !a.allProjects && !groupedByProject && ctx.project !== void 0) {
+			where.push({ OR: [{ project: { eq: ctx.project } }, { project: { eq: null } }] });
+			ev.push({
+				span: "(context)",
+				role: "scope",
+				detail: `project = ${ctx.project} or none`
+			});
+		}
+	}
+	const params = {};
+	if (where.length === 1) params.where = where[0];
+	else if (where.length > 1) params.where = { AND: where };
+	if (a.order !== null) {
+		params.orderBy = [{ createdAt: a.order }];
+		params.limit = 1;
+	}
+	const answer = a.askField !== null ? a.askField.group ? `group:${a.askField.field}` : `field:${a.askField.field}` : a.count ? "count" : a.order !== null || a.ids.length === 1 ? "single" : "rows";
+	return {
+		type,
+		frame: { [`${pack.namespace}/${type}`]: { params } },
+		answer,
+		evidence: ev,
+		residual: contentWords(tokens)
+	};
+}
+/** A clause's field name: the field itself, case-insensitively, then the rulings' and built-in aliases. */
+function resolveField(raw, fields, rulings) {
+	const lower = raw.toLowerCase();
+	const direct = Object.keys(fields).find((f) => f.toLowerCase() === lower);
+	if (direct !== void 0) return direct;
+	const aliased = own(rulings.fieldAliases, lower) ?? own(BUILTIN_FIELD_ALIASES, lower);
+	return aliased !== void 0 && Object.hasOwn(fields, aliased) ? aliased : null;
+}
+/** A clause value as the field's type, or undefined when it is not one. */
+function coerce(raw, f) {
+	if (f.valueType === "number") {
+		const n = Number(raw);
+		return Number.isFinite(n) ? n : void 0;
+	}
+	if (f.valueType === "boolean") return raw === "true" ? true : raw === "false" ? false : void 0;
+	return raw;
+}
+/** Types that have every field the clauses name, sorted. */
+function typesWithFields(pack, clauses, rulings) {
+	return Object.entries(pack.types).filter(([, t]) => clauses.every((c) => resolveField(c.field, t.fields, rulings) !== null)).map(([name]) => name).sort();
+}
+/** Marks unused tokens naming `field` as explained; true when any did. */
+function creditFieldWords(tokens, field) {
+	if (field === void 0) return false;
+	let hit = false;
+	for (const phrase of field.phrases) {
+		const parts = phrase.split(" ");
+		const stem = (parts[parts.length - 1] ?? "").replace(/s$/, "");
+		for (let i = 0; i + parts.length <= tokens.length; i++) {
+			const slice = tokens.slice(i, i + parts.length);
+			if (slice.some((t) => t.used)) continue;
+			const text = slice.map((t) => t.text).join(" ");
+			const last = slice[slice.length - 1]?.text ?? "";
+			const head = slice.slice(0, -1).map((t) => t.text).join(" ");
+			const headWant = parts.slice(0, -1).join(" ");
+			if (text === phrase || head === headWant && stem.length >= 3 && last.startsWith(stem)) {
+				for (const t of slice) t.used = true;
+				hit = true;
+			}
+		}
+	}
+	return hit;
+}
+function contentWords(tokens) {
+	return tokens.filter((t) => !t.used && !GLUE.has(t.text) && !/^\d+$/.test(t.text)).map((t) => t.text);
+}
+/** Claims the longest n-grams (up to `max` words) for which `accept` returns true. */
+function claimNgrams(tokens, max, accept) {
+	for (let n = max; n >= 1; n--) for (let i = 0; i + n <= tokens.length; i++) {
+		const slice = tokens.slice(i, i + n);
+		if (slice.some((t) => t.used)) continue;
+		const at = slice.map((_, j) => i + j);
+		if (!accept(slice.map((t) => t.text).join(" "), at)) continue;
+		for (const t of slice) t.used = true;
+	}
+}
+/** Type phrases: rulings aliases, then the pack's, plus each multi-word type's first word. Longest first. */
+function buildTypeIndex(pack, rulings) {
+	const map = /* @__PURE__ */ new Map();
+	const add = (phrase, type, plural) => {
+		const e = map.get(phrase) ?? {
+			types: /* @__PURE__ */ new Set(),
+			plural
+		};
+		e.types.add(type);
+		map.set(phrase, e);
+	};
+	const aliased = new Set(Object.keys(rulings.typeAliases ?? {}));
+	for (const [phrase, type] of Object.entries(rulings.typeAliases ?? {})) add(phrase, type, phrase.endsWith("s"));
+	for (const [name, t] of Object.entries(pack.types)) {
+		const words = splitWords(name);
+		const singulars = /* @__PURE__ */ new Set([words.join(" "), words[words.length - 1] ?? ""]);
+		for (const p of [...t.phrases, name.toLowerCase()]) if (!aliased.has(p)) add(p, name, !singulars.has(p) && p !== name.toLowerCase());
+		if (words.length > 1) {
+			const first = words[0];
+			if (!aliased.has(first)) add(first, name, false);
+			if (!aliased.has(pluralize(first))) add(pluralize(first), name, true);
+		}
+	}
+	return [...map].map(([phrase, e]) => ({
+		phrase,
+		types: [...e.types].sort(),
+		plural: e.plural
+	})).sort((x, y) => y.phrase.split(" ").length - x.phrase.split(" ").length || x.phrase.localeCompare(y.phrase));
+}
+function fieldNamed(pack, word) {
+	return Object.values(pack.types).some((t) => Object.values(t.fields).some((f) => f.phrases.includes(word)));
+}
+/** Types every value can be read as, sorted. */
+function typesCovering(pack, values) {
+	let acc = null;
+	for (const v of values) {
+		const types = new Set(v.alias !== void 0 ? v.alias.map((x) => x.type) : (own(pack.values, v.key) ?? []).map((r) => r.type));
+		acc = acc === null ? [...types] : acc.filter((t) => types.has(t));
+	}
+	return [...acc ?? []].sort();
+}
+/** Types whose `status` enum has a terminal value. */
+function closableTypes(pack) {
+	return Object.entries(pack.types).filter(([, t]) => t.fields.status?.enum?.some((v) => CLOSED.includes(v)) === true).map(([name]) => name).sort();
+}
+/**
+* The field a value reads as when it fits several on one type: a field named
+* in the question first, then the most categorical (fewest distinct values,
+* enum size for enums), then name order.
+*/
+function pickField(candidates, fields, words) {
+	const unique = [...new Set(candidates)];
+	const text = ` ${words.join(" ")} `;
+	const stem = (p) => p.replace(/s$/, "");
+	const named = unique.filter((f) => fields[f]?.phrases.some((p) => text.includes(` ${p} `) || stem(p).length >= 3 && words.some((w) => w !== p && w.startsWith(stem(p)))));
+	const pool = named.length > 0 ? named : unique;
+	const size = (f) => fields[f]?.enum?.length ?? fields[f]?.distinct ?? Number.MAX_SAFE_INTEGER;
+	return [...pool].sort((x, y) => size(x) - size(y) || x.localeCompare(y))[0];
+}
+function claimTime(tokens, asOf) {
+	let found = null;
+	claimNgrams(tokens, 3, (key) => {
+		if (found !== null) return false;
+		const range = rangeFor(key, asOf);
+		if (range === null) return false;
+		found = {
+			span: key,
+			range
+		};
+		return true;
+	});
+	return found;
+}
+
+//#endregion
+//#region src/judge/judge.ts
+/** String scalar fields a binding may target, as `Type.field`. */
+function bindableFields(pack, types) {
+	const out = [];
+	for (const type of types) for (const [name, f] of Object.entries(pack.types[type]?.fields ?? {})) if (f.kind === "scalar" && f.valueType === "string" && f.indexed) out.push(`${type}.${name}`);
+	return out.sort();
+}
+/** Build the options, the prompt and the schema for one escalated parse. */
+function buildJudgePrompt(question, result, pack, rulings = {}, rejected = []) {
+	const allTypes = Object.keys(pack.types).sort();
+	const words = [...new Set(result.residual)];
+	const fields = bindableFields(pack, result.candidates.length > 0 ? [...new Set(result.candidates.map((c) => c.type))] : allTypes);
+	const branch = (action, args = {}) => ({
+		type: "object",
+		properties: {
+			action: { const: action },
+			...args
+		},
+		required: ["action", ...Object.keys(args)]
+	});
+	const schema = { anyOf: [
+		...result.candidates.length > 0 ? [branch("pick", { candidate: {
+			type: "integer",
+			enum: result.candidates.map((_, i) => i)
+		} })] : [],
+		branch("type", { type: {
+			type: "string",
+			enum: allTypes
+		} }),
+		...words.length > 0 && fields.length > 0 ? [branch("bind", {
+			word: {
+				type: "string",
+				enum: words
+			},
+			field: {
+				type: "string",
+				enum: fields
+			},
+			op: {
+				type: "string",
+				enum: [
+					"eq",
+					"startsWith",
+					"contains"
+				]
+			}
+		})] : [],
+		branch("recall"),
+		branch("clarify"),
+		branch("refuse"),
+		branch("escalate")
+	] };
+	const ruled = (t) => Object.entries(rulings.typeAliases ?? {}).filter(([, type]) => type === t).map(([phrase]) => phrase);
+	const typeLines = allTypes.map((t) => {
+		const note = rulings.typeNotes?.[t];
+		const names = [...ruled(t), ...(pack.types[t]?.phrases ?? []).slice(0, 4)].join(", ");
+		return `- ${t}${note !== void 0 ? ` (${note})` : ""}: ${names}`;
+	});
+	const candidateLines = result.candidates.map((c, i) => `${i}. ${c.type} where ${JSON.stringify(Object.values(c.frame)[0]?.params.where ?? {})} (from: ${c.evidence.map((e) => `"${e.span}"=${e.detail}`).join("; ")})`);
+	return {
+		system: [
+			"You choose how a question about a data store should be answered. You do not write queries.",
+			"A deterministic parser read the question first and could not settle it. Choose ONE action:",
+			"- pick: one reading answers the WHOLE question as asked; leftover words are noise. If the",
+			"  question needs rows of one type found through another, no single reading answers it.",
+			"- type: the question lists or counts rows of one type; the parser then builds the query from the",
+			"  question's own words (dates, \"latest\", known values). Prefer this when a type clearly fits.",
+			"- bind: a leftover word is a value stored in a field: eq = the whole value, startsWith = a prefix",
+			"  of a name or id, contains = a word inside a title or subject. Never bind a word that only",
+			"  describes the question (e.g. \"status\", \"called\").",
+			"- recall: the question asks what is known ABOUT a topic (free-text subject words, not field values);",
+			"  semantic search over the text answers it.",
+			"- clarify: RARE. Only when the question has two specific readings and nothing in it chooses one.",
+			"  Missing detail is not ambiguity: if a type or a topic fits, choose type or recall.",
+			"- refuse: the question is not about this store at all, or asks to change data.",
+			"- escalate: none of these answers the question as asked (e.g. it needs two queries chained).",
+			"",
+			`Types in the "${pack.namespace}" store:`,
+			...typeLines
+		].join("\n"),
+		user: [
+			`Question: ${question}`,
+			`Parser: ${result.status}${result.reason !== void 0 ? ` (${result.reason})` : ""}`,
+			...result.evidence !== void 0 && result.evidence.length > 0 ? [`Understood so far: ${result.evidence.map((e) => `"${e.span}" = ${e.role} ${e.detail}`).join("; ")}`] : [],
+			...candidateLines.length > 0 ? ["Readings:", ...candidateLines] : [],
+			...words.length > 0 ? [`Leftover words: ${words.join(", ")}`] : [],
+			...rejected.map((r) => `Already tried and rejected: ${r}`)
+		].join("\n"),
+		schema
+	};
+}
+/** Check a reply against the options it was offered. */
+function checkChoice(reply, prompt) {
+	if (typeof reply !== "object" || reply === null) return "reply is not an object";
+	const r = reply;
+	const branch = (prompt.schema.anyOf ?? []).find((b) => b.properties.action?.const === r.action);
+	if (branch === void 0) return `action ${JSON.stringify(r.action)} was not offered`;
+	const choice = { action: r.action };
+	for (const key of branch.required) {
+		if (key === "action") continue;
+		if (branch.properties[key]?.enum?.includes(r[key]) !== true) return `${String(r.action)} needs an offered ${key}`;
+		choice[key] = r[key];
+	}
+	return choice;
+}
+/** A binding becomes a one-question ruling, so the parser applies it like any other. */
+function withBinding(rulings, choice) {
+	const [type, field] = choice.field.split(".");
+	const word = choice.word;
+	const alias = choice.op === "startsWith" ? {
+		type,
+		field,
+		startsWith: word
+	} : choice.op === "contains" ? {
+		type,
+		field,
+		contains: word
+	} : {
+		type,
+		field,
+		eq: word
+	};
+	return {
+		...rulings ?? {},
+		valueAliases: {
+			...rulings?.valueAliases ?? {},
+			[word]: [alias]
+		}
+	};
+}
+/** Why a binding cannot be applied, or null when it grounds. */
+async function verifyBinding(choice, earlier, pack, opts) {
+	const [type, field] = choice.field.split(".");
+	const word = choice.word;
+	const def = own(own(pack.types, type)?.fields, field);
+	if (def === void 0) return `${type}.${field} is not a field`;
+	if (!def.operators.includes(choice.op)) return `${type}.${field} does not accept ${choice.op}`;
+	if (def.enum !== void 0 && choice.op === "eq") {
+		if (![...def.enum, ...Object.keys(def.aliases ?? {})].map((v) => v.toLowerCase()).includes(word.toLowerCase())) return `"${word}" is not a ${type}.${field} value`;
+	}
+	if (opts.exists === void 0) return null;
+	const predicate = (c) => ({ [c.field.split(".")[1]]: { [c.op]: c.word } });
+	const same = earlier.filter((c) => c.field.startsWith(`${type}.`));
+	const where = same.length === 0 ? predicate(choice) : { AND: [...same, choice].map(predicate) };
+	if (!await opts.exists(type, where)) return same.length === 0 ? `no ${type} has ${field} ${choice.op} "${word}"` : `no ${type} matches it together with ${same.map((c) => `"${c.word}"`).join(", ")}`;
+	return null;
+}
+/**
+* Parse; while the parse is not resolved, ask the judge and apply its choice.
+* A refused, clarified or resolved parse never reaches the model.
+*/
+async function parseWithJudge(question, pack, ctx, judge, opts = {}) {
+	const trail = [];
+	let context = ctx;
+	let result = parseQuestion(question, pack, context);
+	const rejected = [];
+	const bound = [];
+	for (let round = 0; round < (opts.rounds ?? 3); round++) {
+		if (result.status === "resolved") return {
+			status: "resolved",
+			candidate: result.candidates[0],
+			trail
+		};
+		if (result.status === "refuse" || result.status === "clarify") return {
+			status: result.status,
+			reason: result.reason ?? "",
+			trail
+		};
+		const step = { parse: {
+			status: result.status,
+			...result.reason !== void 0 ? { reason: result.reason } : {}
+		} };
+		trail.push(step);
+		const prompt = buildJudgePrompt(question, result, pack, context.rulings, rejected);
+		const checked = checkChoice(await judge.decide(prompt, opts.signal), prompt);
+		if (typeof checked === "string") {
+			step.rejected = checked;
+			break;
+		}
+		step.choice = checked;
+		switch (checked.action) {
+			case "pick": return {
+				status: "resolved",
+				candidate: result.candidates[checked.candidate],
+				trail
+			};
+			case "recall": return {
+				status: "recall",
+				query: question,
+				trail
+			};
+			case "clarify":
+			case "refuse": return {
+				status: checked.action,
+				reason: "judge",
+				trail
+			};
+			case "type":
+				context = {
+					...context,
+					forceType: checked.type
+				};
+				break;
+			case "escalate": return {
+				status: "escalated",
+				result,
+				trail
+			};
+			case "bind": {
+				const why = await verifyBinding(checked, bound, pack, opts);
+				if (why !== null) {
+					step.rejected = why;
+					rejected.push(`bind ${checked.word} to ${checked.field} (${why})`);
+					continue;
+				}
+				bound.push(checked);
+				context = {
+					...context,
+					rulings: withBinding(context.rulings, checked)
+				};
+				break;
+			}
+		}
+		result = parseQuestion(question, pack, context);
+	}
+	if (result.status === "resolved") return {
+		status: "resolved",
+		candidate: result.candidates[0],
+		trail
+	};
+	return {
+		status: "escalated",
+		result,
+		trail
+	};
+}
+
+//#endregion
+//#region src/ask/run.ts
+const RECALL_K = 10;
+/** The frame a candidate needs to run: its params plus every projectable field of its type. */
+function executable(c, pack) {
+	const [key, value] = Object.entries(c.frame)[0];
+	const fields = { id: true };
+	for (const [name, f] of Object.entries(own(pack.types, c.type)?.fields ?? {})) if (f.kind !== "metadata") fields[name] = true;
+	return { [key]: {
+		params: value.params,
+		fields
+	} };
+}
+async function rows(c, source, http, deps, handoff) {
+	const frame = executable(c, deps.pack);
+	const key = Object.keys(frame)[0];
+	const env = await deps.engine.query(frame, http);
+	const present = env.data !== void 0 && key in env.data;
+	return {
+		kind: "rows",
+		frame,
+		answer: c.answer,
+		data: present ? env.data?.[key] : void 0,
+		...env.errors !== void 0 && env.errors.length > 0 ? { errors: env.errors } : {},
+		source,
+		...handoff !== void 0 ? { handoff } : {}
+	};
+}
+async function recall(query, ns, http, deps) {
+	const frame = { "recall/Hit": {
+		params: {
+			to: query,
+			namespace: ns,
+			k: RECALL_K
+		},
+		fields: {
+			id: true,
+			namespace: true,
+			type: true,
+			score: true,
+			row: true
+		}
+	} };
+	const env = await deps.engine.query(frame, http);
+	const hits = env.data?.["recall/Hit"];
+	return {
+		kind: "recall",
+		query,
+		hits: Array.isArray(hits) ? hits : void 0,
+		...env.errors !== void 0 && env.errors.length > 0 ? { errors: env.errors } : {}
+	};
+}
+function clarify(question, reason, candidates, pack) {
+	const seen = /* @__PURE__ */ new Set();
+	const options = [];
+	for (const c of candidates) {
+		if (seen.has(c.type)) continue;
+		seen.add(c.type);
+		const phrase = own(pack.types, c.type)?.phrases[0] ?? c.type;
+		options.push({
+			label: `${phrase} (${c.type})`,
+			question,
+			type: c.type
+		});
+	}
+	return {
+		kind: "clarify",
+		question,
+		reason,
+		options
+	};
+}
+const isAborted = (http) => http.signal?.aborted === true;
+async function* runAsk(req, http, deps) {
+	const ctx = {
+		asOf: (deps.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+		rulings: deps.pack.rulings,
+		...req.project !== void 0 ? { project: req.project } : {},
+		...req.type !== void 0 ? { forceType: req.type } : {}
+	};
+	const first = parseQuestion(req.question, deps.pack, ctx);
+	const best = first.candidates[0];
+	yield {
+		event: "parsed",
+		status: first.status,
+		...best !== void 0 ? { frame: executable(best, deps.pack) } : {},
+		evidence: best?.evidence ?? first.evidence ?? [],
+		residual: first.residual,
+		...first.reason !== void 0 ? { reason: first.reason } : {}
+	};
+	if (isAborted(http)) return yield { event: "done" };
+	let outcome;
+	if (first.status === "resolved" && best !== void 0) outcome = await rows(best, "parser", http, deps);
+	else if (first.status === "refuse") outcome = {
+		kind: "refuse",
+		reason: first.reason ?? "refused"
+	};
+	else if (first.status === "clarify") outcome = clarify(req.question, first.reason ?? "which did you mean?", first.candidates, deps.pack);
+	else if (deps.judge === void 0) outcome = best !== void 0 ? await rows(best, "handoff", http, deps, "judge not configured") : clarify(req.question, "judge not configured", first.candidates, deps.pack);
+	else {
+		yield {
+			event: "judging",
+			reason: first.reason ?? first.status
+		};
+		const ac = new AbortController();
+		const timer = setTimeout(() => ac.abort(/* @__PURE__ */ new Error("judge timeout")), deps.judgeTimeoutMs ?? 2e4);
+		const onAbort = () => ac.abort(http.signal?.reason);
+		http.signal?.addEventListener("abort", onAbort, { once: true });
+		if (isAborted(http)) onAbort();
+		let judged;
+		try {
+			const judging = parseWithJudge(req.question, deps.pack, ctx, deps.judge, {
+				signal: ac.signal,
+				exists: async (type, where) => {
+					if (ac.signal.aborted) return false;
+					const key = `${deps.pack.namespace}/${type}`;
+					const r = (await deps.engine.query({ [key]: {
+						params: {
+							where,
+							limit: 1
+						},
+						fields: { id: true }
+					} }, http)).data?.[key];
+					return Array.isArray(r) && r.length > 0;
+				}
+			});
+			judging.catch(() => {});
+			const gone = new Promise((_, reject) => {
+				const fire = () => reject(ac.signal.reason);
+				if (ac.signal.aborted) fire();
+				else ac.signal.addEventListener("abort", fire, { once: true });
+			});
+			judged = await Promise.race([judging, gone]);
+		} catch {
+			judged = void 0;
+		} finally {
+			clearTimeout(timer);
+			http.signal?.removeEventListener("abort", onAbort);
+		}
+		if (isAborted(http)) return yield { event: "done" };
+		if (judged === void 0) outcome = best !== void 0 ? await rows(best, "handoff", http, deps, "judge unavailable") : clarify(req.question, "judge unavailable", first.candidates, deps.pack);
+		else {
+			yield {
+				event: "judged",
+				status: judged.status,
+				trail: judged.trail
+			};
+			switch (judged.status) {
+				case "resolved":
+					outcome = await rows(judged.candidate, "judge", http, deps);
+					break;
+				case "recall":
+					outcome = await recall(judged.query, deps.pack.namespace, http, deps);
+					break;
+				case "refuse":
+					outcome = {
+						kind: "refuse",
+						reason: judged.reason
+					};
+					break;
+				case "clarify":
+					outcome = clarify(req.question, judged.reason, first.candidates, deps.pack);
+					break;
+				case "escalated": outcome = best !== void 0 ? await rows(best, "handoff", http, deps, "judge could not decide") : clarify(req.question, "judge could not decide", first.candidates, deps.pack);
+			}
+		}
+	}
+	yield {
+		event: "outcome",
+		outcome
+	};
+	yield { event: "done" };
+}
+
+//#endregion
+//#region src/judge/ollama.ts
+/**
+* Ollama's native chat endpoint with `format` set to the question's schema,
+* so decoding cannot leave the offered options. Thinking off, temperature 0
+* and a fixed seed. Sends no `num_ctx` / `keep_alive`: Ollama shares one
+* runner per model, and differing options force a reload for every client
+* (see substrate-embedder's README).
+*/
+var OllamaJudge = class {
+	#config;
+	constructor(config) {
+		this.#config = {
+			...config,
+			baseUrl: config.baseUrl.replace(/\/+$/, "")
+		};
+	}
+	async decide(prompt, signal) {
+		const timeout = AbortSignal.timeout(this.#config.timeoutMs ?? 6e4);
+		const res = await fetch(`${this.#config.baseUrl}/api/chat`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			signal: signal === void 0 ? timeout : AbortSignal.any([timeout, signal]),
+			body: JSON.stringify({
+				model: this.#config.model,
+				stream: false,
+				think: false,
+				format: prompt.schema,
+				options: {
+					temperature: 0,
+					seed: 0
+				},
+				messages: [{
+					role: "system",
+					content: prompt.system
+				}, {
+					role: "user",
+					content: prompt.user
+				}]
+			})
+		});
+		if (!res.ok) throw new Error(`ollama ${res.status} ${res.statusText}`);
+		const body = await res.json();
+		return JSON.parse(body.message?.content ?? "");
+	}
+};
+
+//#endregion
+//#region src/rulings/schema.ts
+const ValueAliasSchema = z.object({
+	type: z.string().min(1),
+	field: z.string().min(1),
+	in: z.array(z.string()).optional(),
+	eq: z.string().optional(),
+	startsWith: z.string().optional(),
+	contains: z.string().optional()
+}).strict().refine((v) => [
+	v.in,
+	v.eq,
+	v.startsWith,
+	v.contains
+].filter((x) => x !== void 0).length === 1, { message: "a value alias names exactly one of in, eq, startsWith, contains" });
+const record = z.record(z.string(), z.string());
+const NamespaceRulingsSchema = z.object({
+	unscopedTypes: z.array(z.string()).optional(),
+	typeAliases: record.optional(),
+	fieldAliases: record.optional(),
+	liveStatus: record.optional(),
+	timeField: record.optional(),
+	typeNotes: record.optional(),
+	valueAliases: z.record(z.string(), z.array(ValueAliasSchema)).optional()
+}).strict();
+/** Per top-level key: records merge entry-by-entry (override wins), arrays replace. */
+function mergeRulings(declared, override) {
+	if (override === void 0) return declared;
+	const out = { ...declared };
+	for (const [key, value] of Object.entries(override)) {
+		const prior = out[key];
+		out[key] = Array.isArray(value) || prior === void 0 || Array.isArray(prior) ? value : {
+			...prior,
+			...value
+		};
+	}
+	return out;
+}
+/** The effective rulings for one namespace's schema, plus anything that was dropped. */
+function readRulings(schema, override) {
+	const warnings = [];
+	let declared = {};
+	const raw = schema.annotations?.nl;
+	if (raw !== void 0) {
+		const parsed = NamespaceRulingsSchema.safeParse(raw);
+		if (parsed.success) declared = parsed.data;
+		else {
+			const where = parsed.error.issues.map((i) => i.path.join(".") || "(root)").join(", ");
+			warnings.push(`declared rulings are invalid and were ignored (${where})`);
+		}
+	}
+	return {
+		rulings: mergeRulings(declared, override),
+		warnings
+	};
+}
+
+//#endregion
+//#region src/pack/build.ts
+/** Longest value worth matching as a whole phrase. */
+const MAX_VALUE_LENGTH = 64;
+/**
+* A field is vocabulary when its values are labels rather than prose. The
+* test is length, not distinct count: an `area` with hundreds of one-word
+* values is vocabulary, a `title` with a dozen sentences is not.
+*/
+const MAX_MEAN_WORDS = 3;
+/** Server-managed fields every type can filter on, with their value type. */
+const METADATA_FIELDS = {
+	createdAt: {
+		valueType: "date",
+		phrases: ["created", "created at"]
+	},
+	updatedAt: {
+		valueType: "date",
+		phrases: ["updated", "updated at"]
+	},
+	createdById: {
+		valueType: "string",
+		phrases: ["created by", "author"]
+	},
+	createdByKind: {
+		valueType: "string",
+		phrases: ["created by kind"]
+	},
+	updatedById: {
+		valueType: "string",
+		phrases: ["updated by"]
+	},
+	updatedByKind: {
+		valueType: "string",
+		phrases: ["updated by kind"]
+	}
+};
+/**
+* Builds the NL vocabulary for one namespace. Pure: the same schema, operator
+* table and profile always give byte-identical output, with sorted keys.
+*/
+function buildNamespacePack(input) {
+	const { namespace, schema, operators, profile } = input;
+	const maxDistinct = input.maxDistinct ?? 1e3;
+	const types = {};
+	const refs = [];
+	for (const typeName of Object.keys(schema.types).sort()) {
+		const declared = schema.types[typeName]?.fields ?? {};
+		const fields = {};
+		for (const name of Object.keys(declared).sort()) {
+			const def = declared[name];
+			const field = packField(name, def, operators);
+			fields[name] = field;
+			for (const value of field.enum ?? []) refs.push({
+				type: typeName,
+				field: name,
+				value
+			});
+			for (const alias of Object.keys(field.aliases ?? {})) refs.push({
+				type: typeName,
+				field: name,
+				value: alias
+			});
+			const observed = profile?.types[typeName]?.[name];
+			if (observed !== void 0 && field.indexed && isStringy(def) && !observed.truncated && observed.values.length <= maxDistinct && areLabels(observed.values)) {
+				for (const value of observed.values) refs.push({
+					type: typeName,
+					field: name,
+					value
+				});
+				field.distinct = observed.values.length;
+			}
+		}
+		for (const [name, meta] of Object.entries(METADATA_FIELDS)) {
+			if (name in fields) continue;
+			fields[name] = {
+				name,
+				kind: "metadata",
+				valueType: meta.valueType,
+				indexed: true,
+				operators: [...operators[`scalar.${meta.valueType}`] ?? []],
+				phrases: meta.phrases
+			};
+		}
+		types[typeName] = {
+			name: typeName,
+			phrases: typePhrases(typeName),
+			fields: sortKeys(fields)
+		};
+	}
+	return {
+		namespace,
+		schemaVersion: schema.schemaVersion,
+		types,
+		values: indexValues(refs)
+	};
+}
+function packField(name, def, operators) {
+	const phrases = uniqueSorted([splitWords(name).join(" "), name.toLowerCase()]);
+	switch (def.kind) {
+		case "scalar": return {
+			name,
+			kind: "scalar",
+			valueType: def.type,
+			indexed: def.indexed === true,
+			operators: [...operators[`scalar.${def.type}`] ?? []],
+			phrases,
+			...def.enum !== void 0 ? { enum: [...def.enum] } : {},
+			...def.aliases !== void 0 ? { aliases: { ...def.aliases } } : {}
+		};
+		case "crossRef": return {
+			name,
+			kind: "crossRef",
+			target: def.type,
+			indexed: def.indexed === true,
+			operators: [...operators.crossRef ?? []],
+			phrases
+		};
+		case "list": return {
+			name,
+			kind: "list",
+			indexed: def.indexed === true,
+			operators: [...operators.list ?? []],
+			phrases
+		};
+		default: return {
+			name,
+			kind: "struct",
+			indexed: false,
+			operators: [],
+			phrases
+		};
+	}
+}
+function areLabels(values) {
+	if (values.length === 0) return false;
+	return values.reduce((n, v) => n + v.trim().split(/\s+/).length, 0) / values.length <= MAX_MEAN_WORDS;
+}
+/** A string scalar, or a list of string scalars: the fields whose values read as words. */
+function isStringy(def) {
+	if (def.kind === "scalar") return def.type === "string";
+	return def.kind === "list" && def.of.kind === "scalar" && def.of.type === "string";
+}
+function typePhrases(typeName) {
+	const words = splitWords(typeName);
+	const last = words[words.length - 1] ?? typeName.toLowerCase();
+	const head = words.slice(0, -1);
+	const out = [[...head, last].join(" "), [...head, pluralize(last)].join(" ")];
+	if (head.length > 0) out.push(last, pluralize(last));
+	return uniqueSorted(out);
+}
+function indexValues(refs) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const ref of refs) {
+		const key = ref.value.trim().toLowerCase();
+		if (key.length === 0 || key.length > MAX_VALUE_LENGTH) continue;
+		const bucket = byKey.get(key) ?? /* @__PURE__ */ new Map();
+		bucket.set(`${ref.type}\u0000${ref.field}`, ref);
+		byKey.set(key, bucket);
+	}
+	const out = {};
+	for (const key of [...byKey.keys()].sort()) {
+		const bucket = byKey.get(key);
+		out[key] = [...bucket.keys()].sort().map((k) => bucket.get(k));
+	}
+	return out;
+}
+function sortKeys(obj) {
+	return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]));
+}
+
+//#endregion
+//#region src/pack/profile.ts
+/**
+* Distinct values of every indexed string field (and indexed list-of-string
+* field) in the namespace, reading up to `maxRows` rows per type. A field that
+* passes `maxDistinct` is marked truncated and stops growing.
+*/
+async function profileNamespace(input) {
+	const maxDistinct = input.maxDistinct ?? 1e3;
+	const maxRows = input.maxRows ?? 1e4;
+	const types = {};
+	for (const typeName of Object.keys(input.schema.types).sort()) {
+		const declared = input.schema.types[typeName]?.fields ?? {};
+		const fields = Object.keys(declared).filter((f) => profiled(declared[f]));
+		if (fields.length === 0) continue;
+		const seen = new Map(fields.map((f) => [f, /* @__PURE__ */ new Set()]));
+		const truncated = /* @__PURE__ */ new Set();
+		let cursor;
+		let rowsRead = 0;
+		do {
+			const page = await input.read(typeName, fields, cursor);
+			rowsRead += page.rows.length;
+			for (const row of page.rows) for (const f of fields) {
+				if (truncated.has(f)) continue;
+				const raw = row[f];
+				const values = Array.isArray(raw) ? raw : [raw];
+				const set = seen.get(f);
+				for (const v of values) {
+					if (typeof v !== "string" || v.length === 0) continue;
+					set.add(v);
+					if (set.size > maxDistinct) {
+						truncated.add(f);
+						break;
+					}
+				}
+			}
+			cursor = page.nextCursor;
+		} while (cursor !== void 0 && truncated.size < fields.length && rowsRead < maxRows);
+		const out = {};
+		for (const f of [...fields].sort()) {
+			const values = [...seen.get(f)].sort();
+			const isTruncated = truncated.has(f);
+			if (values.length === 0 && !isTruncated) continue;
+			out[f] = {
+				values: isTruncated ? values.slice(0, maxDistinct) : values,
+				truncated: isTruncated
+			};
+		}
+		types[typeName] = out;
+	}
+	return { types };
+}
+function profiled(def) {
+	if (def.kind === "scalar") return def.type === "string" && def.indexed === true;
+	return def.kind === "list" && def.indexed === true && def.of.kind === "scalar" && def.of.type === "string";
+}
+
+//#endregion
+//#region src/pack/service.ts
+/**
+* Packs are built under the CALLER's request: the profile reads distinct
+* values through `engine.query(frame, req)`, so row policy applies and a
+* pack can never disclose a value its caller could not read. Hence the
+* principal is part of the cache key.
+*/
+var PackService = class {
+	#opts;
+	#cache = /* @__PURE__ */ new Map();
+	#inflight = /* @__PURE__ */ new Map();
+	#warned = /* @__PURE__ */ new Set();
+	constructor(opts) {
+		this.#opts = opts;
+	}
+	async get(ns, req) {
+		const schemas = this.#opts.engine.federatedSchema();
+		const schema = Object.hasOwn(schemas, ns) ? schemas[ns] : void 0;
+		if (schema === void 0) return void 0;
+		const now = (this.#opts.now ?? Date.now)();
+		const ttl = this.#opts.ttlMs ?? 3e5;
+		const key = `${ns}\u0000${schema.schemaVersion}\u0000${principalKey(req)}`;
+		const hit = this.#cache.get(key);
+		if (hit !== void 0 && now - hit.at < ttl) {
+			this.#cache.delete(key);
+			this.#cache.set(key, hit);
+			return {
+				pack: hit.pack,
+				etag: hit.etag
+			};
+		}
+		let pending = this.#inflight.get(key);
+		if (pending === void 0) {
+			pending = this.#build(ns, schema, req, now).finally(() => this.#inflight.delete(key));
+			this.#inflight.set(key, pending);
+		}
+		const entry = await pending;
+		this.#cache.delete(key);
+		this.#cache.set(key, entry);
+		const max = this.#opts.maxEntries ?? 256;
+		while (this.#cache.size > max) {
+			const oldest = this.#cache.keys().next().value;
+			if (oldest === void 0) break;
+			this.#cache.delete(oldest);
+		}
+		return {
+			pack: entry.pack,
+			etag: entry.etag
+		};
+	}
+	async #build(ns, schema, req, now) {
+		const { rulings, warnings } = readRulings(schema, own(this.#opts.rulings, ns));
+		const warnKey = `${ns}\u0000${schema.schemaVersion}`;
+		if (warnings.length > 0 && !this.#warned.has(warnKey)) {
+			this.#warned.add(warnKey);
+			(this.#opts.log ?? console.warn)(`substrate-nl: ${ns}: ${warnings.join("; ")}`);
+		}
+		const read = async (type, fields, cursor) => {
+			const frameKey = `${ns}/${type}`;
+			const env = await this.#opts.engine.query({ [frameKey]: {
+				params: cursor !== void 0 ? { cursor } : {},
+				fields: Object.fromEntries(fields.map((f) => [f, true]))
+			} }, req);
+			const rows = env.data?.[frameKey];
+			const page = env._pagination?.[frameKey];
+			return {
+				rows: Array.isArray(rows) ? rows : [],
+				nextCursor: page?.hasMore === true ? page.nextCursor : void 0
+			};
+		};
+		const profile = await profileNamespace({
+			schema,
+			read
+		});
+		const pack = {
+			...buildNamespacePack({
+				namespace: ns,
+				schema,
+				operators: this.#opts.engine.operators(ns) ?? {},
+				profile
+			}),
+			rulings,
+			warnings
+		};
+		return {
+			pack,
+			etag: `"${createHash("sha256").update(JSON.stringify(pack)).digest("hex").slice(0, 16)}"`,
+			at: now
+		};
+	}
+};
+/**
+* The Identity canonicalised, less `expiresAt`: a custom row policy may key on
+* any claim (a tenant, say), so no other subset is safe to share a cached pack
+* across, while a token's expiry changes with every refresh.
+*/
+function principalKey(req) {
+	const id = req.identity;
+	if (id === void 0) return "\0anon";
+	const { expiresAt: _expiresAt, ...stable } = id;
+	return JSON.stringify(canonical(stable));
+}
+function canonical(v) {
+	if (Array.isArray(v)) return v.map(canonical);
+	if (v !== null && typeof v === "object") return Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, x]) => [k, canonical(x)]));
+	return v;
+}
+
+//#endregion
+//#region src/ask/encode.ts
+/** Same headers as substrate-compose's SSE routes (not exported from its entry). */
+const SSE_HEADERS = {
+	"content-type": "text/event-stream",
+	"cache-control": "no-store",
+	"x-accel-buffering": "no"
+};
+/** One named SSE event. JSON.stringify emits no raw newline, so one data line is safe. */
+function sseEvent(name, data) {
+	return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+function wireName(ev) {
+	if (ev.event === "outcome") return [ev.outcome.kind, ev.outcome];
+	const { event, ...rest } = ev;
+	return [event, rest];
+}
+function toSseStream(events, onCancel, onError) {
+	const enc = new TextEncoder();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const next = await events.next();
+				if (next.done === true) return controller.close();
+				const [name, data] = wireName(next.value);
+				controller.enqueue(enc.encode(sseEvent(name, data)));
+			} catch (err) {
+				onError?.(err);
+				controller.enqueue(enc.encode(sseEvent("error", {
+					code: "nl_engine_error",
+					message: "NL query failed"
+				})));
+				controller.close();
+			}
+		},
+		async cancel() {
+			onCancel?.();
+			await events.return(void 0);
+		}
+	});
+}
+async function toJson(events) {
+	const trail = [];
+	let outcome = null;
+	for await (const ev of events) {
+		trail.push(ev);
+		if (ev.event === "outcome") outcome = ev.outcome;
+	}
+	return {
+		outcome,
+		trail
+	};
+}
+
+//#endregion
+//#region src/routes.ts
+const VARY = { vary: "authorization" };
+const engineFailure = (req, err, log) => {
+	if (req.signal?.aborted === true) return { status: 499 };
+	log(err);
+	return jsonResponse(502, {
+		error: "NL query failed",
+		code: "nl_engine_error"
+	});
+};
+const str = (v) => typeof v === "string" && v.length > 0;
+/** Longest question parsed; the same bound recall puts on its query text. */
+const MAX_QUESTION_CHARS = 8192;
+function askHandler(deps) {
+	const log = deps.log ?? ((err) => console.error("substrate-nl:", err));
+	return async (req) => {
+		const parsed = parseJsonBody(req);
+		if (!parsed.ok) return parsed.response;
+		const body = parsed.value;
+		if (body === null || typeof body !== "object" || Array.isArray(body)) return error400("body must be a JSON object: { namespace, question, project?, type? }");
+		if (!str(body.namespace)) return error400("body.namespace must be a non-empty string");
+		if (!str(body.question)) return error400("body.question must be a non-empty string");
+		if (body.question.length > MAX_QUESTION_CHARS) return error400(`body.question is longer than ${MAX_QUESTION_CHARS} characters`);
+		for (const k of ["project", "type"]) if (body[k] !== void 0 && !str(body[k])) return error400(`body.${k} must be a non-empty string when given`);
+		const ask = {
+			namespace: body.namespace,
+			question: body.question,
+			...str(body.project) ? { project: body.project } : {},
+			...str(body.type) ? { type: body.type } : {}
+		};
+		let served;
+		try {
+			served = await deps.packs.get(ask.namespace, req);
+		} catch (err) {
+			return engineFailure(req, err, log);
+		}
+		if (served === void 0) return jsonResponse(404, {
+			error: `unknown namespace '${ask.namespace}'`,
+			code: "nl_unknown_namespace"
+		});
+		if (ask.type !== void 0 && !Object.hasOwn(served.pack.types, ask.type)) return error400(`unknown type '${ask.type}'`);
+		const events = runAsk(ask, req, {
+			pack: served.pack,
+			engine: deps.engine,
+			...deps.judge !== void 0 ? { judge: deps.judge } : {},
+			...deps.judgeTimeoutMs !== void 0 ? { judgeTimeoutMs: deps.judgeTimeoutMs } : {},
+			...deps.now !== void 0 ? { now: deps.now } : {}
+		});
+		if ((req.headers.accept ?? "").toLowerCase().includes("text/event-stream")) return {
+			status: 200,
+			headers: SSE_HEADERS,
+			body: toSseStream(events, void 0, log)
+		};
+		try {
+			return jsonResponse(200, await toJson(events));
+		} catch (err) {
+			return engineFailure(req, err, log);
+		}
+	};
+}
+function packHandler(deps) {
+	const log = deps.log ?? ((err) => console.error("substrate-nl:", err));
+	return async (req) => {
+		const ns = req.params.ns ?? "";
+		let served;
+		try {
+			served = await deps.packs.get(ns, req);
+		} catch (err) {
+			return engineFailure(req, err, log);
+		}
+		if (served === void 0) return jsonResponse(404, {
+			error: `unknown namespace '${ns}'`,
+			code: "nl_unknown_namespace"
+		});
+		if (req.headers["if-none-match"] === served.etag) return {
+			status: 304,
+			headers: {
+				etag: served.etag,
+				...VARY
+			}
+		};
+		return jsonResponse(200, served.pack, {
+			etag: served.etag,
+			"cache-control": "private, no-cache",
+			...VARY
+		});
+	};
+}
+
+//#endregion
+//#region src/plugin.ts
+/** The routes rely on `KernelRouteClaim.capability`, which every 1.x host honours. */
+const CONTRACT_VERSION = ">=1.0.0-alpha.0 <2.0.0";
+function createNlPlugin(cfg) {
+	const packs = new PackService({
+		engine: cfg.engine,
+		...cfg.rulings !== void 0 ? { rulings: cfg.rulings } : {},
+		...cfg.packTtlMs !== void 0 ? { ttlMs: cfg.packTtlMs } : {}
+	});
+	const deps = {
+		engine: cfg.engine,
+		packs,
+		...cfg.judge !== void 0 ? { judge: cfg.judge } : {},
+		...cfg.judgeTimeoutMs !== void 0 ? { judgeTimeoutMs: cfg.judgeTimeoutMs } : {}
+	};
+	return {
+		name: "substrate-nl",
+		contractVersion: CONTRACT_VERSION,
+		kernelRoutes: [{
+			path: "nl",
+			method: "POST",
+			handler: askHandler(deps),
+			capability: "read"
+		}, {
+			path: "nl/pack/:ns",
+			method: "GET",
+			handler: packHandler(deps),
+			capability: "read"
+		}]
+	};
+}
+
+//#endregion
+//#region src/bootstrap.ts
+/**
+* Structured-config bootstrap for `@mnmal-ai/substrate-nl`.
+*
+* Operator-overridable (`<pluginDir>/substrate-nl.config.json`):
+*   - `judge`     optional; Ollama for the constrained judge. Absent = parser-only:
+*                 every escalation is an honest hand-off.
+*   - `rulings`   optional; per-namespace override merged over declared rulings.
+*   - `packTtlMs` how long a served pack is reused. Default 300000.
+* Host-supplied (`hostDeps.nlEngine`): schema, operators and query access.
+*/
+const JudgeSchema = z.object({
+	baseUrl: z.url(),
+	model: z.string().min(1),
+	timeoutMs: z.number().int().positive().default(2e4)
+}).strict();
+const NlBootstrapConfigSchema = z.object({
+	judge: JudgeSchema.optional(),
+	rulings: z.record(z.string(), NamespaceRulingsSchema).optional(),
+	packTtlMs: z.number().int().positive().default(3e5)
+}).strict();
+const bootstrap = defineBootstrap.kernel({
+	schema: NlBootstrapConfigSchema,
+	build: (config, deps) => createNlPlugin({
+		engine: deps.nlEngine,
+		packTtlMs: config.packTtlMs,
+		...config.judge !== void 0 ? {
+			judge: new OllamaJudge(config.judge),
+			judgeTimeoutMs: config.judge.timeoutMs
+		} : {},
+		...config.rulings !== void 0 ? { rulings: config.rulings } : {}
+	})
+});
+
+//#endregion
+export { askHandler as a, profileNamespace as c, mergeRulings as d, readRulings as f, parseQuestion as g, parseWithJudge as h, createNlPlugin as i, buildNamespacePack as l, runAsk as m, bootstrap as n, packHandler as o, OllamaJudge as p, CONTRACT_VERSION as r, PackService as s, NlBootstrapConfigSchema as t, NamespaceRulingsSchema as u };