@contentrain/decide 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1164 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { canonicalStringify } from "@contentrain/types";
+//#region src/audit.ts
+function toAuditRecord(decision, at, tenant) {
+	const record = {
+		at,
+		tenant,
+		kind: decision.kind,
+		version: decision.version,
+		key: decision.key,
+		shape: decision.shape,
+		confidence: decision.confidence,
+		source: decision.source,
+		ms: decision.ms
+	};
+	if (decision.choice !== void 0) record.choice = decision.choice;
+	if (decision.score !== void 0) record.score = decision.score;
+	if (decision.proposed !== void 0) record.proposed = decision.proposed;
+	if (decision.unreviewed) record.unreviewed = true;
+	if (decision.fallback) record.fallback = decision.fallback;
+	if (decision.model) record.model = decision.model;
+	if (decision.cost) {
+		record.input_tokens = decision.cost.input_tokens;
+		record.output_tokens = decision.cost.output_tokens;
+		if (decision.cost.usd !== void 0) record.usd = decision.cost.usd;
+	}
+	return record;
+}
+var MemoryAuditLog = class {
+	records = [];
+	async write(records) {
+		this.records.push(...records);
+	}
+};
+/** Appends to a JSONL file (conventionally `decisions.jsonl`), one line per decision. */
+var JsonlAuditLog = class {
+	constructor(path) {
+		this.path = path;
+	}
+	async write(records) {
+		if (!records.length) return;
+		await mkdir(dirname(this.path), { recursive: true });
+		await appendFile(this.path, records.map((record) => `${JSON.stringify(record)}\n`).join(""));
+	}
+};
+//#endregion
+//#region src/batch.ts
+const DEFAULT_BATCH = {
+	maxItems: 32,
+	maxTokens: 32e3
+};
+const estimateTokens = (text) => Math.ceil(text.length / 3);
+/**
+* Split item costs into consecutive batches. `fixed` is what every request
+* pays once (the preamble); `costs[i]` what item i adds (its line and its
+* questions). An item too large for any batch goes alone.
+*/
+function planBatches(costs, fixed, limits = {}) {
+	const maxItems = limits.maxItems ?? DEFAULT_BATCH.maxItems;
+	const maxTokens = limits.maxTokens ?? DEFAULT_BATCH.maxTokens;
+	if (!Number.isInteger(maxItems) || maxItems < 1) throw new RangeError(`maxItems must be a positive integer, got ${maxItems}`);
+	const batches = [];
+	let current = [];
+	let tokens = fixed;
+	costs.forEach((cost, i) => {
+		if (current.length && (current.length >= maxItems || tokens + cost > maxTokens)) {
+			batches.push(current);
+			current = [];
+			tokens = fixed;
+		}
+		current.push(i);
+		tokens += cost;
+	});
+	if (current.length) batches.push(current);
+	return batches;
+}
+//#endregion
+//#region src/budget.ts
+/** A per-tenant cap on provider decisions per UTC day, held in memory. */
+var MemoryDailyBudget = class {
+	spent = /* @__PURE__ */ new Map();
+	constructor(perDay) {
+		this.perDay = perDay;
+		if (!Number.isInteger(perDay) || perDay < 0) throw new RangeError(`perDay must be a non-negative integer, got ${perDay}`);
+	}
+	async take(tenant, count, now) {
+		const slot = `${tenant}\n${now.toISOString().slice(0, 10)}`;
+		const used = this.spent.get(slot) ?? 0;
+		const granted = Math.max(0, Math.min(count, this.perDay - used));
+		this.spent.set(slot, used + granted);
+		return granted;
+	}
+	used(tenant, now) {
+		return this.spent.get(`${tenant}\n${now.toISOString().slice(0, 10)}`) ?? 0;
+	}
+};
+/**
+* Closed → open after `failures` consecutive failed requests; open → half-open
+* after `cooldownMs`, where the next request decides: success closes it, a
+* failure opens it for another cooldown.
+*/
+var CircuitBreaker = class {
+	consecutive = 0;
+	openedAt;
+	limit;
+	cooldownMs;
+	now;
+	constructor(options = {}) {
+		this.limit = options.failures ?? 3;
+		this.cooldownMs = options.cooldownMs ?? 6e4;
+		this.now = options.now ?? Date.now;
+	}
+	get state() {
+		if (this.openedAt === void 0) return "closed";
+		return this.now() - this.openedAt >= this.cooldownMs ? "half_open" : "open";
+	}
+	/** Whether a request may go out now. */
+	allows() {
+		return this.state !== "open";
+	}
+	success() {
+		this.consecutive = 0;
+		this.openedAt = void 0;
+	}
+	failure() {
+		this.consecutive++;
+		if (this.openedAt !== void 0 || this.consecutive >= this.limit) this.openedAt = this.now();
+	}
+};
+//#endregion
+//#region src/cache.ts
+function cacheKey(kind, version, shape, shaped) {
+	return createHash("sha256").update(`${kind}\n${version}\n${shape}\n${canonicalStringify(shaped)}`).digest("hex");
+}
+var MemoryDecisionCache = class {
+	entries = /* @__PURE__ */ new Map();
+	get size() {
+		return this.entries.size;
+	}
+	async get(key) {
+		return this.entries.get(key);
+	}
+	async set(key, value) {
+		this.entries.set(key, value);
+	}
+};
+/**
+* One `{"key","value"}` line per answer, appended. Read once, on first use;
+* a later line for the same key wins. A torn last line (a crash mid-append) is
+* skipped rather than failing the run — the answer is asked for again.
+*/
+var JsonlDecisionCache = class {
+	loaded;
+	constructor(path) {
+		this.path = path;
+	}
+	load() {
+		this.loaded ??= readFile(this.path, "utf8").then((text) => readCacheLines(text), (error) => {
+			if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+			throw error;
+		});
+		return this.loaded;
+	}
+	async get(key) {
+		return (await this.load()).get(key);
+	}
+	async set(key, value) {
+		(await this.load()).set(key, value);
+		await mkdir(dirname(this.path), { recursive: true });
+		await appendFile(this.path, `${JSON.stringify({
+			key,
+			value
+		})}\n`);
+	}
+};
+function readCacheLines(text) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const { key, value } = JSON.parse(line);
+			if (typeof key === "string" && value && typeof value === "object") entries.set(key, value);
+		} catch {}
+	}
+	return entries;
+}
+//#endregion
+//#region src/jev.ts
+const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+const JEV_TOKEN_ENV = "CONTENTRAIN_JEW_API_TOKEN";
+const DEFAULT_JEV_MODEL = "jev-latest";
+var JevError = class extends Error {
+	constructor(message, status, timeout = false) {
+		super(message);
+		this.status = status;
+		this.timeout = timeout;
+		this.name = "JevError";
+	}
+};
+/**
+* The request one batch sends: the kind's header from the first item, then one
+* `Item <n>: ` line per item; every item's questions keyed `item<n>_<suffix>`.
+*/
+function buildJevRequest(spec, shaped) {
+	const jev = spec.jev;
+	if (!jev) throw new TypeError(`kind ${spec.kind} has no Jev prompt`);
+	const header = shaped.length && jev.header ? jev.header(shaped[0]) : "";
+	const lines = shaped.map((item, i) => `Item ${i + 1}: ${jev.render(item)}`);
+	const questions = {};
+	shaped.forEach((_, i) => {
+		const prefix = `item${i + 1}`;
+		for (const [suffix, question] of Object.entries(jev.questions(prefix))) questions[`${prefix}_${suffix}`] = question;
+	});
+	return {
+		state: header + lines.join("\n"),
+		questions
+	};
+}
+/**
+* Hash of everything that shapes a kind's provider request: the model, the
+* batch limits, whether items are grouped, and the request built from two
+* copies of the kind's probe (header, line format, questions, criteria). A
+* change to any of them changes the hash, and with it every cache key.
+*/
+function requestShapeHash(spec, model = DEFAULT_JEV_MODEL) {
+	const jev = spec.jev;
+	if (!jev) return "none";
+	const shape = {
+		model,
+		batch: jev.batch ?? null,
+		grouped: Boolean(jev.group),
+		request: buildJevRequest(spec, [jev.probe, jev.probe])
+	};
+	return createHash("sha256").update(canonicalStringify(shape)).digest("hex").slice(0, 16);
+}
+function createJevProvider(options = {}) {
+	const env = options.env ?? process.env;
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? 15e3;
+	const model = options.model ?? "jev-latest";
+	return {
+		name: "jev",
+		model,
+		available: () => Boolean(env[JEV_TOKEN_ENV]?.trim()),
+		async ask(spec, shaped) {
+			const token = env[JEV_TOKEN_ENV]?.trim();
+			if (!token) throw new JevError(`${JEV_TOKEN_ENV} is not set`, void 0);
+			const { state, questions } = buildJevRequest(spec, shaped);
+			let response;
+			try {
+				response = await doFetch(JEV_ENDPOINT, {
+					method: "POST",
+					headers: {
+						"Authorization": `Bearer ${token}`,
+						"Content-Type": "application/json"
+					},
+					body: JSON.stringify({
+						state,
+						model,
+						questions
+					}),
+					signal: AbortSignal.timeout(timeoutMs)
+				});
+			} catch (error) {
+				const name = error.name;
+				if (name === "TimeoutError" || name === "AbortError") throw new JevError(`Jev did not answer within ${timeoutMs}ms`, void 0, true);
+				throw new JevError(`Jev request failed: ${redact$1(String(error.message ?? error), token)}`, void 0);
+			}
+			const text = await response.text();
+			if (!response.ok) throw new JevError(`Jev answered HTTP ${response.status}: ${redact$1(text.slice(0, 200), token)}`, response.status);
+			let body;
+			try {
+				body = JSON.parse(text);
+			} catch {
+				throw new JevError("Jev answered with a body that is not JSON", response.status);
+			}
+			return readJevResponse(spec, shaped.length, body);
+		}
+	};
+}
+/** Per-item outcomes from a systemone response. An item whose answers are missing or malformed gets `undefined`. */
+function readJevResponse(spec, count, body) {
+	const jev = spec.jev;
+	const root = body && typeof body === "object" ? body : {};
+	const answers = root.answers && typeof root.answers === "object" ? root.answers : {};
+	const outcomes = [];
+	for (let i = 1; i <= count; i++) {
+		const own = {};
+		let complete = true;
+		for (const suffix of Object.keys(jev.questions(`item${i}`))) {
+			const answer = readAnswer(answers[`item${i}_${suffix}`]);
+			if (!answer) complete = false;
+			else own[suffix] = answer;
+		}
+		outcomes.push(complete ? jev.read(own) : void 0);
+	}
+	const usage = root.usage;
+	return {
+		outcomes,
+		...usage && typeof usage.input_tokens === "number" && typeof usage.output_tokens === "number" ? { usage: {
+			input_tokens: usage.input_tokens,
+			output_tokens: usage.output_tokens
+		} } : {},
+		...typeof root.model === "string" ? { model: root.model } : {}
+	};
+}
+const isUnit = (value) => typeof value === "number" && value >= 0 && value <= 1;
+function readAnswer(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const answer = value;
+	const probabilities = answer.probabilities && typeof answer.probabilities === "object" ? { probabilities: answer.probabilities } : {};
+	if (answer.type === "choice" && typeof answer.choice === "string" && isUnit(answer.confidence)) return {
+		type: "choice",
+		choice: answer.choice,
+		confidence: answer.confidence,
+		...probabilities
+	};
+	if (answer.type === "score" && typeof answer.score === "number" && Number.isFinite(answer.score) && isUnit(answer.confidence)) return {
+		type: "score",
+		score: answer.score,
+		confidence: answer.confidence,
+		...probabilities
+	};
+	if (answer.type === "noul" && isUnit(answer.noul)) return {
+		type: "noul",
+		noul: answer.noul
+	};
+}
+function redact$1(text, token) {
+	return text.split(token).join("[redacted]");
+}
+//#endregion
+//#region src/kinds/shape.ts
+const URL = /\b(?:https?|ftp):\/\/\S+|\bwww\.\S+/gi;
+const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
+const PATH = /(^|[\s("'=])\/[\w.~%-]+(?:\/[\w.~%-]*)*/g;
+function scrubText(text, max) {
+	const clean = text.replace(URL, "<url>").replace(EMAIL, "<email>").replace(PATH, "$1<path>").replace(/\s+/g, " ").trim();
+	return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+/** A slug-like identifier (post-type name, family name): lower-case word characters and dashes only. */
+function scrubSlug(value, max = 40) {
+	return value.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, max);
+}
+/** A finite number, or undefined. */
+function finite(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+//#endregion
+//#region src/kinds/eligibility-band.ts
+const ELIGIBILITY_CHOICES = [
+	"eligible",
+	"access_blocked",
+	"page_only",
+	"custom_type"
+];
+const NEEDS_HUMAN = "needs_human";
+const MIN_POSTS = 2;
+/** Posts and custom entries within this factor of each other are the band. */
+const BAND_FACTOR = 2;
+function shapeEligibility(input) {
+	const rest = input.rest;
+	const counts = /* @__PURE__ */ new Map();
+	for (const type of rest.postTypes ?? []) {
+		if (type.slug === "post" || type.slug === "page" || !((type.count ?? 0) > 0)) continue;
+		const slug = scrubSlug(type.slug);
+		counts.set(slug, (counts.get(slug) ?? 0) + (type.count ?? 0));
+	}
+	return {
+		access: input.access,
+		rest_reachable: Boolean(rest.reachable),
+		posts: rest.counts?.posts ?? null,
+		pages: rest.counts?.pages ?? null,
+		post_samples: rest.samples?.posts?.length ?? 0,
+		page_samples: rest.samples?.pages?.length ?? 0,
+		custom_types: [...counts].map(([slug, count]) => ({
+			slug,
+			count
+		})).toSorted((a, b) => a.slug.localeCompare(b.slug))
+	};
+}
+const certain = (choice) => ({
+	choice,
+	confidence: 1,
+	final: true
+});
+const tentative = (choice) => ({
+	choice,
+	confidence: .5,
+	final: false
+});
+function eligibilityRule(input) {
+	const site = shapeEligibility(input);
+	if (site.access !== "open" || !site.rest_reachable) return certain("access_blocked");
+	const postCount = site.posts ?? site.post_samples;
+	const customCount = site.custom_types.reduce((sum, type) => sum + type.count, 0);
+	const pages = site.page_samples || (site.pages ?? 0);
+	if (site.post_samples >= MIN_POSTS) {
+		const verdict = customCount <= postCount ? "eligible" : "custom_type";
+		return customCount > 0 && customCount * BAND_FACTOR >= postCount && postCount * BAND_FACTOR >= customCount ? tentative(verdict) : certain(verdict);
+	}
+	const verdict = site.custom_types.length ? "custom_type" : pages ? "page_only" : "access_blocked";
+	return site.post_samples === 1 ? tentative(verdict) : certain(verdict);
+}
+function renderEligibility(site) {
+	const custom = site.custom_types.length ? site.custom_types.map((type) => `${type.slug}=${type.count}`).join(", ") : "none";
+	return [
+		`access=${site.access}`,
+		`rest=${site.rest_reachable ? "reachable" : "unreachable"}`,
+		`posts=${site.posts ?? "unknown"} (sampled ${site.post_samples})`,
+		`pages=${site.pages ?? "unknown"} (sampled ${site.page_samples})`,
+		`custom post types: ${custom}`
+	].join("; ");
+}
+function readEligibility(answers) {
+	const answer = answers.eligibility;
+	if (answer?.type !== "choice") return void 0;
+	return {
+		choice: answer.choice,
+		confidence: answer.confidence,
+		...answer.probabilities ? { probabilities: answer.probabilities } : {}
+	};
+}
+function eligibilityQuestions(prefix) {
+	return { eligibility: {
+		type: "choice",
+		instructions: `${prefix}: where does this site's content live, and can the engine move it?`,
+		criteria: {
+			eligible: "Standard blog posts carry the site's content; moving posts and pages moves what matters.",
+			custom_type: "The content lives mainly in custom post types (products, portfolio, members); moving posts and pages alone leaves it behind.",
+			page_only: "No real blog: a corporate or brochure site whose content is its pages.",
+			access_blocked: "What the scan could see is not the site's real content; authorized access is needed to reach it."
+		}
+	} };
+}
+const eligibilityBand = {
+	kind: "eligibility_band",
+	version: "1",
+	choices: ELIGIBILITY_CHOICES,
+	shape: shapeEligibility,
+	rule: eligibilityRule,
+	jev: {
+		header: () => "WordPress sites considered for migration. Each item is what a public discovery scan counted on one site. The migration engine moves standard posts and pages only.\n",
+		render: renderEligibility,
+		questions: eligibilityQuestions,
+		read: readEligibility,
+		probe: {
+			access: "open",
+			rest_reachable: true,
+			posts: 20,
+			pages: 3,
+			post_samples: 5,
+			page_samples: 3,
+			custom_types: [{
+				slug: "product",
+				count: 30
+			}]
+		}
+	},
+	lowConfidence: {
+		threshold: .5,
+		choice: NEEDS_HUMAN
+	}
+};
+//#endregion
+//#region src/kinds/punch-item.ts
+const PUNCH_CLASSES = [
+	"product_defect",
+	"source_limit",
+	"cosmetic",
+	"measurement"
+];
+const PUNCH_CLASS_CRITERIA = {
+	product_defect: "Migration engine'in ürettiği çıktıda bir kusur/hata — üretilen sayfada bir şey yanlış (ör. yanlış görsel tekrar ediyor, bağlantı kırık, içerik markup'ta eksik).",
+	source_limit: "Kaynak sitenin kendi yapısından gelen bir sınır — içerik zaten kaynakta veri olarak ayrıştırılamaz durumda (ör. tema markup'ına gömülü, API'de yok), migration engine bunu değiştiremez.",
+	cosmetic: "Teslimi engellemeyen küçük görsel fark — kullanıcı deneyimini gerçekten bozmayan, göz ardı edilebilir bir fark.",
+	measurement: "Ölçüm/araç belirsizliği — sorunun kendisi değil, ölçüm sürecinin (skor eşiği, örneklem, zaman aşımı) ne olduğunu net söyleyememesi."
+};
+/** Severity rubric, levels 0–3 (Jev's score scale). Level n here is severity n+1 on a 1–4 scale. */
+const PUNCH_SEVERITY_CRITERIA = [
+	"Teslimi engellemez — göz ardı edilebilir.",
+	"Küçük, düşük öncelik — teslim edilebilir, sonra bakılabilir.",
+	"Teslimden önce ele alınmalı — müşteri fark edebilir ama kesin reddetmez.",
+	"Müşteri fark eder ve reddeder — teslim öncesi mutlaka çözülmeli."
+];
+function shapePunchItem(input) {
+	const site = input.site ?? {};
+	const identity = site.name ?? site.url ?? "";
+	return {
+		label: scrubText(String(input.label ?? ""), 120),
+		reason: scrubText(String(input.reason ?? ""), 500),
+		linked: Boolean(input.link),
+		site: {
+			group: identity ? createHash("sha256").update(identity).digest("hex").slice(0, 16) : "",
+			decision: typeof site.decision === "string" ? scrubText(site.decision, 40) : null,
+			median: finite(site.median) ?? null,
+			mobile_median: finite(site.mobile_median) ?? null
+		}
+	};
+}
+const SIGNATURES = [
+	[/ölçülemedi|genellik kanıtlanmadı/i, "measurement"],
+	[/gövde yuvası yok|tam sayfa klon/i, "source_limit"],
+	[/hero sızıntısı|medya kaybı|dinamik liste bağlanmadı/i, "product_defect"]
+];
+function punchItemRule(input) {
+	const reason = String(input.reason ?? "");
+	const hit = SIGNATURES.find(([pattern]) => pattern.test(reason));
+	return hit ? {
+		choice: hit[1],
+		confidence: 1,
+		final: false
+	} : void 0;
+}
+function punchHeader(item) {
+	return `Site: <site> (<url>)\nGenel karar: ${item.site.decision}\nMedyan kalite skoru: ${item.site.median}, mobil: ${item.site.mobile_median}\n`;
+}
+function renderPunchItem(item) {
+	return `etiket="${item.label}", link="${item.linked ? "<url>" : "(yok)"}", neden="${item.reason}"`;
+}
+function punchQuestions(prefix) {
+	return {
+		class: {
+			type: "choice",
+			instructions: `${prefix} için: bu kalemin kök nedeni nedir?`,
+			criteria: PUNCH_CLASS_CRITERIA
+		},
+		severity: {
+			type: "score",
+			instructions: `${prefix} için: bu kalem ne kadar ciddi?`,
+			criteria: PUNCH_SEVERITY_CRITERIA
+		},
+		needs_human: {
+			type: "noul",
+			instructions: `${prefix} kalemi, teslim öncesi bir insanın karar vermesini gerektiriyor (otomatik/açık bir düzeltme değil, yargı gerektiriyor).`
+		}
+	};
+}
+function readPunchItem(answers) {
+	const cls = answers.class;
+	const severity = answers.severity;
+	if (cls?.type !== "choice" || severity?.type !== "score") return void 0;
+	return {
+		choice: cls.choice,
+		score: severity.score,
+		confidence: Math.min(cls.confidence, severity.confidence),
+		...cls.probabilities ? { probabilities: cls.probabilities } : {}
+	};
+}
+function punchLlmPrompt({ state, questions, count }) {
+	const q = questions.class;
+	const s = questions.severity;
+	const h = questions.needs_human;
+	return [
+		"Aşağıdaki durum bir WordPress → Astro taşıma koşusunun bitirilecekler listesinden bir sitenin kalemlerini içeriyor.",
+		"",
+		"<state>",
+		state,
+		"</state>",
+		"",
+		"Her kalem için üç soruyu yanıtla (itemN yerine kalem numarası):",
+		`1) class — ${q.instructions.replace("item1", "itemN")} Seçenekler:`,
+		...Object.entries(q.criteria).map(([k, v]) => `   - ${k}: ${v}`),
+		`2) severity — ${s.instructions.replace("item1", "itemN")} 0–3 arası tam sayı:`,
+		...s.criteria.map((c, n) => `   ${n}: ${c}`),
+		`3) needs_human — önermenin doğru olma olasılığı (0–1): ${h.instructions.replace("item1", "itemN")}`,
+		"",
+		`Tüm ${count} kalemi record_answers aracıyla, her kalem için bir kayıt olarak ver.`
+	].join("\n");
+}
+/** Jev's 0–3 severity score as a 1–4 level (PoC-1's hand-label scale). */
+const severityLevel = (score) => Math.min(4, Math.max(1, Math.round(score) + 1));
+const punchItem = {
+	kind: "punch_item",
+	version: "2",
+	choices: PUNCH_CLASSES,
+	scoreRange: [0, 3],
+	shape: shapePunchItem,
+	rule: punchItemRule,
+	jev: {
+		header: punchHeader,
+		group: (item) => item.site.group,
+		render: renderPunchItem,
+		questions: punchQuestions,
+		read: readPunchItem,
+		llmPrompt: punchLlmPrompt,
+		batch: { maxItems: 25 },
+		probe: {
+			label: "(aile: post)",
+			reason: "en kötü sayfa 56.4 < 80 (5 sayfa ölçüldü)",
+			linked: false,
+			site: {
+				group: "probe",
+				decision: "KABUL + PUNCH LIST",
+				median: 94.7,
+				mobile_median: 83.9
+			}
+		}
+	}
+};
+//#endregion
+//#region src/kinds/index.ts
+const BUILTIN_KINDS = [punchItem, eligibilityBand];
+//#endregion
+//#region src/llm.ts
+const noopLlmProvider = {
+	name: "llm",
+	available: () => false,
+	ask: async () => {
+		throw new Error("no LLM provider is configured");
+	}
+};
+//#endregion
+//#region src/decide.ts
+function validOutcome(spec, outcome) {
+	if (!outcome) return false;
+	if (outcome.choice !== void 0 && spec.choices && !spec.choices.includes(outcome.choice)) return false;
+	if (outcome.score !== void 0 && spec.scoreRange && (outcome.score < spec.scoreRange[0] || outcome.score > spec.scoreRange[1])) return false;
+	return Number.isFinite(outcome.confidence);
+}
+function fromOutcome(spec, key, shape, outcome, source, ms) {
+	const decision = {
+		kind: spec.kind,
+		version: spec.version,
+		key,
+		shape,
+		confidence: outcome.confidence,
+		source,
+		ms
+	};
+	if (outcome.choice !== void 0) decision.choice = outcome.choice;
+	if (outcome.score !== void 0) decision.score = outcome.score;
+	if (outcome.probabilities) decision.probabilities = outcome.probabilities;
+	return decision;
+}
+/** A provider answer under the kind's confidence floor becomes the kind's human-review choice. */
+function applyFloor(spec, decision) {
+	const floor = spec.lowConfidence;
+	if (!floor || decision.choice === void 0 || decision.confidence >= floor.threshold) return decision;
+	return {
+		...decision,
+		proposed: decision.choice,
+		choice: floor.choice
+	};
+}
+function fallback(spec, item, shape, reason, ms) {
+	return {
+		...item.rule ? fromOutcome(spec, item.key, shape, item.rule, "rule", ms) : {
+			kind: spec.kind,
+			version: spec.version,
+			key: item.key,
+			shape,
+			confidence: 0,
+			source: "rule",
+			ms
+		},
+		unreviewed: true,
+		fallback: reason
+	};
+}
+function fromCache(cached, key, ms) {
+	const { at: _at, source: _source, ...rest } = cached;
+	return {
+		...rest,
+		key,
+		source: "cache",
+		ms
+	};
+}
+function toCached(decision, source, at) {
+	const cached = {
+		kind: decision.kind,
+		version: decision.version,
+		shape: decision.shape,
+		confidence: decision.confidence,
+		source,
+		at
+	};
+	for (const field of [
+		"choice",
+		"score",
+		"probabilities",
+		"proposed",
+		"model"
+	]) if (decision[field] !== void 0) Object.assign(cached, { [field]: decision[field] });
+	return cached;
+}
+/** Split `total` into `parts` integers that sum to it. */
+function share(total, parts, index) {
+	const base = Math.floor(total / parts);
+	return base + (index < total - base * parts ? 1 : 0);
+}
+function createDecider(config = {}) {
+	const kinds = new Map((config.kinds ?? BUILTIN_KINDS).map((spec) => [spec.kind, spec]));
+	const cache = config.cache ?? new MemoryDecisionCache();
+	const now = config.now ?? (() => /* @__PURE__ */ new Date());
+	const providers = [];
+	if (config.jev !== false) providers.push(config.jev ?? createJevProvider());
+	providers.push(config.llm ?? noopLlmProvider);
+	const breakers = new Map(providers.map((p) => [p.name, config.breakers?.[p.name] ?? new CircuitBreaker()]));
+	const jevModel = providers.find((p) => p.name === "jev")?.model ?? "jev-latest";
+	const shapes = /* @__PURE__ */ new Map();
+	const shapeOf = (spec) => {
+		let shape = shapes.get(spec.kind);
+		if (shape === void 0) shapes.set(spec.kind, shape = requestShapeHash(spec, jevModel));
+		return shape;
+	};
+	function cost(provider, usage, parts, index) {
+		if (!usage) return void 0;
+		const input_tokens = share(usage.input_tokens, parts, index);
+		const output_tokens = share(usage.output_tokens, parts, index);
+		const price = config.pricing?.[provider];
+		const usd = price ? (input_tokens * price.inputPerMTok + output_tokens * price.outputPerMTok) / 1e6 : void 0;
+		return usd === void 0 ? {
+			input_tokens,
+			output_tokens
+		} : {
+			input_tokens,
+			output_tokens,
+			usd
+		};
+	}
+	/** Ask one provider about `items`; answered items are returned by key, the rest keep their reason to fall back. */
+	async function ask(provider, spec, shape, items, tenant) {
+		const answered = /* @__PURE__ */ new Map();
+		const reasons = /* @__PURE__ */ new Map();
+		const breaker = breakers.get(provider.name);
+		if (!provider.available() || provider.name === "jev" && !spec.jev) {
+			for (const item of items) reasons.set(item.id, "no_provider");
+			return {
+				answered,
+				reasons
+			};
+		}
+		const groups = /* @__PURE__ */ new Map();
+		for (const item of items) {
+			const group = spec.jev?.group?.(item.shaped) ?? "";
+			groups.set(group, [...groups.get(group) ?? [], item]);
+		}
+		const batches = [];
+		for (const members of groups.values()) {
+			const fixed = spec.jev?.header ? estimateTokens(spec.jev.header(members[0].shaped)) : 0;
+			const costs = members.map((item) => Math.max(1, estimateTokens(JSON.stringify(buildJevRequestFor(spec, item.shaped))) - fixed));
+			for (const batch of planBatches(costs, fixed, spec.jev?.batch ?? config.batch)) batches.push(batch.map((i) => members[i]));
+		}
+		for (const batch of batches) {
+			if (!breaker.allows()) {
+				for (const item of batch) reasons.set(item.id, "circuit_open");
+				continue;
+			}
+			let members = batch;
+			if (config.budget) {
+				const granted = await config.budget.take(tenant, batch.length, now());
+				members = batch.slice(0, granted);
+				for (const item of batch.slice(granted)) reasons.set(item.id, "budget");
+			}
+			if (!members.length) continue;
+			const started = performance.now();
+			try {
+				const answer = await provider.ask(spec, members.map((item) => item.shaped));
+				breaker.success();
+				const ms = Math.round(performance.now() - started);
+				members.forEach((item, i) => {
+					const outcome = answer.outcomes[i];
+					if (!validOutcome(spec, outcome)) {
+						reasons.set(item.id, "no_answer");
+						return;
+					}
+					const decision = fromOutcome(spec, item.key, shape, outcome, provider.name, ms);
+					const spent = cost(provider.name, answer.usage, members.length, i);
+					if (spent) decision.cost = spent;
+					if (answer.model) decision.model = answer.model;
+					answered.set(item.id, applyFloor(spec, decision));
+				});
+			} catch (error) {
+				breaker.failure();
+				const reason = error?.timeout === true ? "timeout" : "error";
+				for (const item of members) reasons.set(item.id, reason);
+			}
+		}
+		return {
+			answered,
+			reasons
+		};
+	}
+	async function decideMany(kind, inputs, options = {}) {
+		const spec = kinds.get(kind);
+		if (!spec) throw new TypeError(`unknown decision kind: ${kind} (known: ${[...kinds.keys()].join(", ")})`);
+		const tenant = options.tenant ?? "default";
+		const shape = shapeOf(spec);
+		const fold = options.fold ?? true;
+		const rule = options.rule === null ? void 0 : options.rule ?? spec.rule;
+		const results = Array.from({ length: inputs.length });
+		const pending = /* @__PURE__ */ new Map();
+		inputs.forEach((input, i) => {
+			const started = performance.now();
+			const shaped = spec.shape(input);
+			const key = cacheKey(spec.kind, spec.version, shape, shaped);
+			const verdict = rule?.(input);
+			const valid = verdict && validOutcome(spec, verdict) ? verdict : void 0;
+			if (valid?.final) {
+				results[i] = fromOutcome(spec, key, shape, valid, "rule", Math.round(performance.now() - started));
+				return;
+			}
+			const id = fold ? key : `${key}#${i}`;
+			const existing = pending.get(id);
+			if (existing) existing.at.push(i);
+			else pending.set(id, {
+				at: [i],
+				id,
+				key,
+				shaped,
+				rule: valid
+			});
+		});
+		let open = [...pending.values()];
+		if (!options.noCache) {
+			const started = performance.now();
+			const hits = await Promise.all(open.map((item) => cache.get(item.key)));
+			const ms = Math.round(performance.now() - started);
+			open = open.filter((item, i) => {
+				const hit = hits[i];
+				if (hit?.kind !== spec.kind || hit.version !== spec.version || hit.shape !== shape) return true;
+				for (const at of item.at) results[at] = fromCache(hit, item.key, ms);
+				return false;
+			});
+		}
+		const lastReason = /* @__PURE__ */ new Map();
+		for (const provider of providers) {
+			if (!open.length) break;
+			const { answered, reasons } = await ask(provider, spec, shape, open, tenant);
+			for (const [id, decision] of answered) {
+				const item = pending.get(id);
+				for (const at of item.at) results[at] = decision;
+				if (!options.noCache) await cache.set(item.key, toCached(decision, provider.name, now().toISOString()));
+			}
+			for (const [id, reason] of reasons) if (reason !== "no_provider" || !lastReason.has(id)) lastReason.set(id, reason);
+			open = open.filter((item) => !answered.has(item.id));
+		}
+		for (const item of open) {
+			const decision = fallback(spec, item, shape, lastReason.get(item.id) ?? "no_provider", 0);
+			for (const at of item.at) results[at] = decision;
+		}
+		if (config.audit) {
+			const at = now().toISOString();
+			await config.audit.write(results.map((decision) => toAuditRecord(decision, at, tenant)));
+		}
+		return results;
+	}
+	return {
+		decideMany,
+		decide: async (kind, input, options) => (await decideMany(kind, [input], options))[0],
+		kinds: () => [...kinds.keys()]
+	};
+}
+function buildJevRequestFor(spec, shaped) {
+	return spec.jev ? buildJevRequest(spec, [shaped]) : shaped;
+}
+let defaultDecider;
+/**
+* Decide with the default decider: built-in kinds, Jev when
+* `CONTENTRAIN_JEW_API_TOKEN` is set, an in-memory cache, no budget, no audit
+* log. Build your own with `createDecider` for anything else.
+*/
+function decide(kind, input, options) {
+	defaultDecider ??= createDecider();
+	return defaultDecider.decide(kind, input, options);
+}
+//#endregion
+//#region src/anthropic.ts
+const ANTHROPIC_ENDPOINT = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_KEY_ENV = "ANTHROPIC_API_KEY";
+const DEFAULT_ANTHROPIC_MODEL = "claude-haiku-4-5-20251001";
+const ANTHROPIC_VERSION = "2023-06-01";
+const MAX_TOKENS = 4096;
+const TOOL_NAME = "record_answers";
+var AnthropicError = class extends Error {
+	constructor(message, status, timeout = false) {
+		super(message);
+		this.status = status;
+		this.timeout = timeout;
+		this.name = "AnthropicError";
+	}
+};
+const itemN = (text) => text.replace(/\bitem1\b/g, "itemN");
+/** The prompt for a kind without its own `llmPrompt`: the state, then every question with its options or rubric. */
+function genericLlmPrompt({ state, questions, count }) {
+	const lines = [
+		"<state>",
+		state,
+		"</state>",
+		"",
+		"Answer these questions for every item (itemN stands for the item's number):"
+	];
+	Object.entries(questions).forEach(([suffix, question], n) => {
+		if (question.type === "choice") {
+			lines.push(`${n + 1}) ${suffix} — ${itemN(question.instructions)} Options:`);
+			for (const [choice, meaning] of Object.entries(question.criteria)) lines.push(`   - ${choice}: ${meaning}`);
+		} else if (question.type === "score") {
+			lines.push(`${n + 1}) ${suffix} — ${itemN(question.instructions)} An integer from 0 to ${question.criteria.length - 1}:`);
+			question.criteria.forEach((meaning, level) => lines.push(`   ${level}: ${meaning}`));
+		} else lines.push(`${n + 1}) ${suffix} — the probability (0–1) that this statement is true: ${itemN(question.instructions)}`);
+	});
+	lines.push("", `Give all ${count} items through the ${TOOL_NAME} tool, one record per item.`);
+	return lines.join("\n");
+}
+/** The forced tool the model answers through: one record per item, one field per question. */
+function answerTool(questions) {
+	const properties = { item: { type: "integer" } };
+	for (const [suffix, question] of Object.entries(questions)) properties[suffix] = question.type === "choice" ? {
+		type: "string",
+		enum: Object.keys(question.criteria)
+	} : question.type === "score" ? {
+		type: "integer",
+		minimum: 0,
+		maximum: question.criteria.length - 1
+	} : {
+		type: "number",
+		minimum: 0,
+		maximum: 1
+	};
+	return {
+		name: TOOL_NAME,
+		description: "Record the answers for every item.",
+		input_schema: {
+			type: "object",
+			properties: { items: {
+				type: "array",
+				items: {
+					type: "object",
+					properties,
+					required: Object.keys(properties)
+				}
+			} },
+			required: ["items"]
+		}
+	};
+}
+/** The Messages API body one batch sends. */
+function buildAnthropicRequest(spec, shaped, model = DEFAULT_ANTHROPIC_MODEL) {
+	const jev = spec.jev;
+	if (!jev) throw new TypeError(`kind ${spec.kind} has no prompt`);
+	const { state } = buildJevRequest(spec, shaped);
+	const questions = jev.questions("item1");
+	const prompt = (jev.llmPrompt ?? genericLlmPrompt)({
+		state,
+		questions,
+		count: shaped.length
+	});
+	return {
+		model,
+		max_tokens: MAX_TOKENS,
+		temperature: 0,
+		tools: [answerTool(questions)],
+		tool_choice: {
+			type: "tool",
+			name: TOOL_NAME
+		},
+		messages: [{
+			role: "user",
+			content: prompt
+		}]
+	};
+}
+/** Hash of the LLM request shape (model, prompt, tool), recorded by a calibration of this provider. */
+function anthropicRequestShapeHash(spec, model = DEFAULT_ANTHROPIC_MODEL) {
+	if (!spec.jev) return "none";
+	const request = buildAnthropicRequest(spec, [spec.jev.probe, spec.jev.probe], model);
+	return createHash("sha256").update(canonicalStringify(request)).digest("hex").slice(0, 16);
+}
+function createAnthropicProvider(options = {}) {
+	const env = options.env ?? process.env;
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const model = options.model ?? "claude-haiku-4-5-20251001";
+	return {
+		name: "llm",
+		model,
+		available: () => Boolean(env[ANTHROPIC_KEY_ENV]?.trim()),
+		async ask(spec, shaped) {
+			const key = env[ANTHROPIC_KEY_ENV]?.trim();
+			if (!key) throw new AnthropicError(`${ANTHROPIC_KEY_ENV} is not set`, void 0);
+			const request = buildAnthropicRequest(spec, shaped, model);
+			let response;
+			try {
+				response = await doFetch(ANTHROPIC_ENDPOINT, {
+					method: "POST",
+					headers: {
+						"x-api-key": key,
+						"anthropic-version": ANTHROPIC_VERSION,
+						"content-type": "application/json"
+					},
+					body: JSON.stringify(request),
+					signal: AbortSignal.timeout(timeoutMs)
+				});
+			} catch (error) {
+				const name = error.name;
+				if (name === "TimeoutError" || name === "AbortError") throw new AnthropicError(`Anthropic did not answer within ${timeoutMs}ms`, void 0, true);
+				throw new AnthropicError(`Anthropic request failed: ${redact(String(error.message ?? error), key)}`, void 0);
+			}
+			const text = await response.text();
+			if (!response.ok) throw new AnthropicError(`Anthropic answered HTTP ${response.status}: ${redact(text.slice(0, 200), key)}`, response.status);
+			let body;
+			try {
+				body = JSON.parse(text);
+			} catch {
+				throw new AnthropicError("Anthropic answered with a body that is not JSON", response.status);
+			}
+			return readAnthropicResponse(spec, shaped.length, body);
+		}
+	};
+}
+/** Per-item outcomes from a Messages API response. An item whose record is missing or malformed gets `undefined`. */
+function readAnthropicResponse(spec, count, body) {
+	const jev = spec.jev;
+	const questions = jev.questions("item1");
+	const root = body && typeof body === "object" ? body : {};
+	const call = (Array.isArray(root.content) ? root.content : []).find((block) => block?.type === "tool_use" && block.name === TOOL_NAME);
+	const input = call?.input && typeof call.input === "object" ? call.input : {};
+	const records = Array.isArray(input.items) ? input.items : [];
+	const outcomes = [];
+	for (let i = 1; i <= count; i++) {
+		const record = records.find((r) => r && typeof r === "object" && r.item === i);
+		const own = {};
+		let complete = Boolean(record);
+		for (const [suffix, question] of Object.entries(questions)) {
+			const answer = record ? readField(question, record[suffix]) : void 0;
+			if (!answer) complete = false;
+			else own[suffix] = answer;
+		}
+		outcomes.push(complete ? jev.read(own) : void 0);
+	}
+	const usage = root.usage;
+	return {
+		outcomes,
+		...usage && typeof usage.input_tokens === "number" && typeof usage.output_tokens === "number" ? { usage: {
+			input_tokens: usage.input_tokens,
+			output_tokens: usage.output_tokens
+		} } : {},
+		...typeof root.model === "string" ? { model: root.model } : {}
+	};
+}
+function readField(question, value) {
+	if (question.type === "choice") return typeof value === "string" && Object.hasOwn(question.criteria, value) ? {
+		type: "choice",
+		choice: value,
+		confidence: 0
+	} : void 0;
+	if (question.type === "score") return Number.isInteger(value) && value >= 0 && value < question.criteria.length ? {
+		type: "score",
+		score: value,
+		confidence: 0
+	} : void 0;
+	return typeof value === "number" && value >= 0 && value <= 1 ? {
+		type: "noul",
+		noul: value
+	} : void 0;
+}
+function redact(text, key) {
+	return text.split(key).join("[redacted]");
+}
+//#endregion
+//#region src/calibration.ts
+/** A request's header and one item line, as a replay key. */
+function replayKey(state, line) {
+	const first = state.search(/^Item 1: /m);
+	return `${first > 0 ? state.slice(0, first) : ""}\u0000${line}`;
+}
+/**
+* A `fetch` that answers systemone requests for `spec` from recorded answers,
+* matching each item by its request header and its rendered line. An item
+* with no recording gets no answers, which the decider treats as `no_answer`.
+* `calls` counts requests.
+*
+* A replay re-reads the answers a model gave once. It checks the code path —
+* shaping, grouping, batching, reading — and says nothing about how the model
+* answers today; only a live run does.
+*/
+function createReplayFetch(spec, cases, model = "replay") {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const recorded of cases) {
+		const { state } = buildJevRequest(spec, [spec.shape(recorded.input)]);
+		const line = /^Item 1: (.*)$/m.exec(state)[1];
+		byKey.set(replayKey(state, line), recorded.answers);
+	}
+	const replay = async (_url, init) => {
+		replay.calls++;
+		const { state } = JSON.parse(String(init?.body));
+		const answers = {};
+		for (const line of state.split("\n")) {
+			const match = /^Item (\d+): (.*)$/.exec(line);
+			const recorded = match ? byKey.get(replayKey(state, match[2])) : void 0;
+			if (!recorded) continue;
+			for (const [suffix, answer] of Object.entries(recorded)) answers[`item${match[1]}_${suffix}`] = answer;
+		}
+		return new Response(JSON.stringify({
+			model,
+			answers
+		}), {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+	};
+	replay.calls = 0;
+	return replay;
+}
+/** Exact class and severity within one level, over every label (an unanswered item counts as a miss). */
+function measurePunchCalibration(labels, decisions) {
+	let answered = 0;
+	let classMatch = 0;
+	let severityWithin1 = 0;
+	const misses = [];
+	labels.forEach((expected, index) => {
+		const decision = decisions[index];
+		if (decision?.choice === void 0 || decision.score === void 0 || decision.unreviewed) {
+			misses.push({
+				index,
+				expected
+			});
+			return;
+		}
+		answered++;
+		const level = severityLevel(decision.score);
+		const classOk = decision.choice === expected.class;
+		const severityOk = Math.abs(level - expected.severity) <= 1;
+		if (classOk) classMatch++;
+		if (severityOk) severityWithin1++;
+		if (!classOk || !severityOk) misses.push({
+			index,
+			expected,
+			choice: decision.choice,
+			level
+		});
+	});
+	const total = labels.length;
+	return {
+		total,
+		answered,
+		classMatch,
+		severityWithin1,
+		classRate: total ? classMatch / total : 0,
+		severityRate: total ? severityWithin1 / total : 0,
+		misses
+	};
+}
+/** Whether repeated runs over the same inputs chose the same class for every item. */
+function stableChoices(runs) {
+	const total = runs[0]?.length ?? 0;
+	let stable = 0;
+	for (let i = 0; i < total; i++) {
+		const choices = new Set(runs.map((run) => run[i]?.choice));
+		if (choices.size === 1 && !choices.has(void 0)) stable++;
+	}
+	return {
+		stable,
+		total
+	};
+}
+//#endregion
+export { ANTHROPIC_ENDPOINT, ANTHROPIC_KEY_ENV, AnthropicError, BUILTIN_KINDS, CircuitBreaker, DEFAULT_ANTHROPIC_MODEL, DEFAULT_BATCH, DEFAULT_JEV_MODEL, ELIGIBILITY_CHOICES, JEV_ENDPOINT, JEV_TOKEN_ENV, JevError, JsonlAuditLog, JsonlDecisionCache, MemoryAuditLog, MemoryDailyBudget, MemoryDecisionCache, NEEDS_HUMAN, PUNCH_CLASSES, PUNCH_CLASS_CRITERIA, PUNCH_SEVERITY_CRITERIA, anthropicRequestShapeHash, buildAnthropicRequest, buildJevRequest, cacheKey, createAnthropicProvider, createDecider, createJevProvider, createReplayFetch, decide, eligibilityBand, eligibilityRule, estimateTokens, genericLlmPrompt, measurePunchCalibration, noopLlmProvider, planBatches, punchItem, punchItemRule, readAnthropicResponse, readJevResponse, requestShapeHash, scrubSlug, scrubText, severityLevel, shapeEligibility, shapePunchItem, stableChoices, toAuditRecord };
+
+//# sourceMappingURL=index.mjs.map