@aigne/afs-llm-bench 1.12.0-beta.5

package/dist/patcher.cjs

@@ -0,0 +1,296 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_errors = require('./errors.cjs');
+require('./runner.cjs');
+let node_fs = require("node:fs");
+let _aigne_afs = require("@aigne/afs");
+let zod = require("zod");
+let node_crypto = require("node:crypto");
+let node_path = require("node:path");
+node_path = require_rolldown_runtime.__toESM(node_path);
+
+//#region src/patcher.ts
+/**
+* Phase 3 — patchCatalog. Merges a results JSON into the ai-device catalog's
+* `entry.afs` subtree. Maintainer tool: directly reads/writes catalog.json
+* (a git-tracked dev artifact, not runtime data) — see decisions.md #24.
+*
+* Invariants (plan.md L459-468):
+*   1. Models missing from results keep their existing `entry.afs` (deep-equal).
+*   2. Only `r.scores` is copied (no other result fields leak into catalog).
+*   3. The written `entry.afs` block has alphabetically sorted keys (clean diff).
+*   4. Atomic write: tmp → rename, no half-written catalog on failure.
+*   5. Prototype-pollution: __proto__/constructor/prototype rejected anywhere.
+*   6. Path traversal: resultsPath must resolve inside resultsRoot.
+*   7. Cache reload via `refreshRegistry` — failures propagate so the caller
+*      knows the catalog landed but routing still sees the previous snapshot.
+*   8. Vault credentials sanitisation: api_key / Authorization / Bearer / etc.
+*      are rejected as field names anywhere in `results.<model>` payloads.
+*
+* Other catalog entries are written unchanged (key order preserved) so the
+* git diff is limited to the `afs` block of patched models.
+*
+* Phase 5: weight tables are no longer inlined — the bench provider passes
+* `loadPolicyWeights` (which the wiring in `bench.ts` resolves through
+* `/dev/ai/score-weights/<name>`), so this module remains independent of
+* ai-device internals.
+*/
+const log = (0, _aigne_afs.makeNsLog)("provider:llm-bench");
+const RESERVED_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype",
+	"__defineGetter__",
+	"__defineSetter__",
+	"__lookupGetter__",
+	"__lookupSetter__"
+]);
+const SENSITIVE_KEY_PATTERNS = [
+	/^api[_-]?key$/i,
+	/^authorization$/i,
+	/^bearer$/i,
+	/^service[_-]?account$/i,
+	/^private[_-]?key$/i,
+	/^client[_-]?secret$/i,
+	/^secret$/i,
+	/^credentials?$/i
+];
+const ALLOWED_RESULT_ENTRY_FIELDS = new Set([
+	"n_samples",
+	"scores",
+	"domains",
+	"stddev",
+	"per_prompt",
+	"errors"
+]);
+const MAX_RESULT_ENTRIES = 500;
+const MAX_N_SAMPLES = 1e3;
+const ScoresSchema = zod.z.object({
+	exploration: zod.z.number().min(0).max(1).optional(),
+	tool_reliability: zod.z.number().min(0).max(1).optional(),
+	self_stop: zod.z.number().min(0).max(1).optional(),
+	parallelism: zod.z.number().min(0).max(1).optional(),
+	efficiency: zod.z.number().min(0).max(1).optional(),
+	instruction_following: zod.z.number().min(0).max(1).optional()
+}).strict();
+const DomainsSchema = zod.z.object({
+	chinese: zod.z.number().min(0).max(1).optional(),
+	english: zod.z.number().min(0).max(1).optional(),
+	coding: zod.z.number().min(0).max(1).optional()
+}).strict();
+const ResultEntrySchema = zod.z.object({
+	n_samples: zod.z.number().int().min(1).max(MAX_N_SAMPLES),
+	scores: ScoresSchema,
+	domains: DomainsSchema.optional(),
+	stddev: zod.z.record(zod.z.string(), zod.z.number()).optional(),
+	per_prompt: zod.z.record(zod.z.string().regex(/^[A-Za-z0-9._-]+$/), ScoresSchema).optional(),
+	errors: zod.z.array(zod.z.unknown()).optional()
+}).strict();
+const JudgeIdSchema = zod.z.string().regex(/^[A-Za-z0-9._-]+$/);
+const JudgeModelSchema = zod.z.union([JudgeIdSchema, zod.z.array(JudgeIdSchema).min(1)]).nullable().optional();
+const ResultsRootSchema = zod.z.object({
+	version: zod.z.string().min(1),
+	judge_model: JudgeModelSchema,
+	config: zod.z.unknown().optional(),
+	results: zod.z.record(zod.z.string().regex(/^[A-Za-z0-9._-]+$/), ResultEntrySchema),
+	outliers: zod.z.unknown().optional()
+}).strict();
+/**
+* Validate raw JSON shape + reject reserved/sensitive keys anywhere.
+* Throws `ValidationError` on any rejection.
+*
+* Layers (in order):
+*   1. Deep-walk: reject `__proto__` / `constructor` / `prototype` and any
+*      key matching a credential pattern (`api_key`, `Authorization`, …).
+*   2. Resource-exhaustion guard: results entries ≤ MAX_RESULT_ENTRIES.
+*   3. Per-entry whitelist: only `n_samples`/`scores`/`domains`/`stddev`.
+*   4. Zod schema parse (z.strict() also catches unknown scores dimensions).
+*/
+function validateResultsShape(raw) {
+	rejectDangerousKeysDeep(raw);
+	if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+		const r = raw.results;
+		if (r && typeof r === "object" && !Array.isArray(r)) {
+			const keys = Object.keys(r);
+			if (keys.length > MAX_RESULT_ENTRIES) throw new require_errors.ValidationError(`results contains ${keys.length} entries; max ${MAX_RESULT_ENTRIES}`);
+			for (const k of keys) {
+				const entry = r[k];
+				if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+					for (const f of Object.keys(entry)) if (!ALLOWED_RESULT_ENTRY_FIELDS.has(f)) throw new require_errors.ValidationError(`unknown field "${f}" in results.${k}`);
+				}
+			}
+		}
+	}
+	const parsed = ResultsRootSchema.safeParse(raw);
+	if (!parsed.success) throw new require_errors.ValidationError(`results JSON is invalid: ${parsed.error.message}`);
+	return {
+		version: parsed.data.version,
+		judge_model: parsed.data.judge_model ?? null,
+		results: parsed.data.results
+	};
+}
+function rejectDangerousKeysDeep(value, p = "$") {
+	if (value === null || typeof value !== "object") return;
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) rejectDangerousKeysDeep(value[i], `${p}[${i}]`);
+		return;
+	}
+	for (const k of Object.keys(value)) {
+		if (RESERVED_KEYS.has(k)) throw new require_errors.ValidationError(`reserved key "${k}" not allowed at ${p}`);
+		for (const re of SENSITIVE_KEY_PATTERNS) if (re.test(k)) throw new require_errors.ValidationError(`sensitive field "${k}" not allowed at ${p}`);
+		rejectDangerousKeysDeep(value[k], `${p}.${k}`);
+	}
+}
+/**
+* Resolve `p` against cwd if relative, then ensure it lives inside `resultsRoot`.
+* Defends against `..` segments and absolute paths that escape the root.
+* Returns the absolute path on success; throws `ValidationError` otherwise.
+*
+* Note: this is purely lexical (no `fs.realpath`) — a maintainer-created
+* symlink inside `resultsRoot` pointing outside is not caught here. The threat
+* model is a maintainer tool, so the lexical check is intentionally cheap; if
+* a symlink-based vector materialises in production, swap to `fs.realpath`.
+*/
+function assertWithinResultsDir(p, resultsRoot) {
+	const absRoot = node_path.resolve(resultsRoot);
+	const abs = node_path.resolve(p);
+	const rel = node_path.relative(absRoot, abs);
+	if (rel === "" || rel.startsWith("..") || node_path.isAbsolute(rel)) throw new require_errors.ValidationError(`results path outside ${resultsRoot}: ${p}`);
+	return abs;
+}
+/**
+* Return a deeply-key-sorted clone of an `afs` block. Plain objects get keys
+* in alphabetical order; arrays preserve order; primitives pass through.
+* Does not mutate input.
+*/
+function sortAfsBlock(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map((v) => sortAfsBlock(v));
+	const sorted = {};
+	for (const k of Object.keys(value).sort()) sorted[k] = sortAfsBlock(value[k]);
+	return sorted;
+}
+const BIOME_LINE_WIDTH = 100;
+const BIOME_INDENT = "  ";
+function stringifyBiomeJSON(value, currentIndent = "", startColumn = 0) {
+	if (value === null) return "null";
+	if (typeof value === "boolean" || typeof value === "number") return String(value);
+	if (typeof value === "string") return JSON.stringify(value);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		if (value.every((v) => v === null || typeof v !== "object")) {
+			const inline = `[${value.map((v) => stringifyBiomeJSON(v)).join(", ")}]`;
+			if (startColumn + inline.length <= BIOME_LINE_WIDTH) return inline;
+		}
+		const inner$1 = currentIndent + BIOME_INDENT;
+		return `[\n${value.map((v) => `${inner$1}${stringifyBiomeJSON(v, inner$1, inner$1.length)}`).join(",\n")}\n${currentIndent}]`;
+	}
+	if (typeof value !== "object") return JSON.stringify(value);
+	const entries = Object.entries(value);
+	if (entries.length === 0) return "{}";
+	const inner = currentIndent + BIOME_INDENT;
+	return `{\n${entries.map(([k, v]) => {
+		const keyPart = `${inner}${JSON.stringify(k)}: `;
+		return `${keyPart}${stringifyBiomeJSON(v, inner, keyPart.length)}`;
+	}).join(",\n")}\n${currentIndent}}`;
+}
+/** Write `obj` as biome-compatible pretty-printed JSON to `target` via tmp+rename. */
+async function atomicWriteJSON(target, obj) {
+	const dir = node_path.dirname(target);
+	await node_fs.promises.mkdir(dir, { recursive: true });
+	const tmp = node_path.join(dir, `.tmp-${(0, node_crypto.randomBytes)(6).toString("hex")}.json`);
+	const payload = `${stringifyBiomeJSON(obj)}\n`;
+	await node_fs.promises.writeFile(tmp, payload, "utf8");
+	try {
+		await node_fs.promises.rename(tmp, target);
+	} catch (err) {
+		await node_fs.promises.rm(tmp, { force: true });
+		throw err;
+	}
+}
+function meanOf(xs) {
+	if (xs.length === 0) return 0;
+	let s = 0;
+	for (const x of xs) s += x;
+	return s / xs.length;
+}
+function getNested(obj, p) {
+	const parts = p.split(".");
+	let cur = obj;
+	for (const k of parts) {
+		if (cur === null || typeof cur !== "object") return void 0;
+		cur = cur[k];
+	}
+	return cur;
+}
+function computeWeightedScore(entry, weights) {
+	let total = 0;
+	for (const [pathKey, w] of Object.entries(weights)) {
+		const v = getNested(entry, pathKey);
+		if (typeof v === "number" && Number.isFinite(v)) total += v * w;
+	}
+	return total;
+}
+async function patchCatalog(input) {
+	const safeResultsPath = assertWithinResultsDir(input.resultsPath, input.resultsRoot);
+	let raw;
+	try {
+		raw = await node_fs.promises.readFile(safeResultsPath, "utf8");
+	} catch (err) {
+		throw new require_errors.ValidationError(`failed to read results: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsedRaw;
+	try {
+		parsedRaw = JSON.parse(raw);
+	} catch (err) {
+		throw new require_errors.ValidationError(`results is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const validated = validateResultsShape(parsedRaw);
+	const catalogText = await node_fs.promises.readFile(input.catalogPath, "utf8");
+	const catalog = JSON.parse(catalogText);
+	if (!Array.isArray(catalog)) throw new require_errors.ValidationError("catalog.json must be an array of entries");
+	const summary = {
+		changes: [],
+		skipped: []
+	};
+	if (catalog.length === 0) return summary;
+	const weightsTable = await input.loadPolicyWeights();
+	if (!weightsTable || typeof weightsTable !== "object" || Array.isArray(weightsTable)) throw new require_errors.ValidationError("loadPolicyWeights must return a plain object of { policy: weights }");
+	for (const [policy, weights] of Object.entries(weightsTable)) if (!weights || typeof weights !== "object" || Array.isArray(weights)) throw new require_errors.ValidationError(`weights for policy "${policy}" must be a plain object`);
+	for (const entry of catalog) {
+		const r = validated.results[entry.model];
+		if (!r) {
+			summary.skipped.push(entry.model);
+			continue;
+		}
+		const before = entry.afs;
+		const policyScores = {};
+		for (const [name, w] of Object.entries(weightsTable)) policyScores[name] = computeWeightedScore(r, w);
+		entry.afs = sortAfsBlock({
+			status: "benchmarked",
+			version: validated.version,
+			last_seen_in_run: validated.version,
+			judge: validated.judge_model,
+			samples: r.n_samples,
+			scores: { ...r.scores },
+			overall: meanOf(Object.values(r.scores)),
+			policyScores,
+			...r.domains ? { domains: { ...r.domains } } : {}
+		});
+		summary.changes.push({
+			model: entry.model,
+			before,
+			after: entry.afs
+		});
+	}
+	await atomicWriteJSON(input.catalogPath, catalog);
+	if (input.refreshRegistry) await input.refreshRegistry();
+	if (summary.changes.length > 0) log.warn(`[patchCatalog] ${summary.changes.length} catalog entr${summary.changes.length === 1 ? "y" : "ies"} updated. Run \`pnpm --filter @aigne/afs-ai-device --filter @aigne/arc-cli build && arc service restart\` to make the daemon's policy router pick them up — the catalog is bundled into ai-device's dist and refreshRegistry only rebuilds the hub registry, not the catalog.`);
+	return summary;
+}
+
+//#endregion
+exports.assertWithinResultsDir = assertWithinResultsDir;
+exports.atomicWriteJSON = atomicWriteJSON;
+exports.patchCatalog = patchCatalog;
+exports.sortAfsBlock = sortAfsBlock;
+exports.validateResultsShape = validateResultsShape;

package/dist/patcher.d.cts

@@ -0,0 +1,119 @@
+//#region src/patcher.d.ts
+/**
+ * Phase 3 — patchCatalog. Merges a results JSON into the ai-device catalog's
+ * `entry.afs` subtree. Maintainer tool: directly reads/writes catalog.json
+ * (a git-tracked dev artifact, not runtime data) — see decisions.md #24.
+ *
+ * Invariants (plan.md L459-468):
+ *   1. Models missing from results keep their existing `entry.afs` (deep-equal).
+ *   2. Only `r.scores` is copied (no other result fields leak into catalog).
+ *   3. The written `entry.afs` block has alphabetically sorted keys (clean diff).
+ *   4. Atomic write: tmp → rename, no half-written catalog on failure.
+ *   5. Prototype-pollution: __proto__/constructor/prototype rejected anywhere.
+ *   6. Path traversal: resultsPath must resolve inside resultsRoot.
+ *   7. Cache reload via `refreshRegistry` — failures propagate so the caller
+ *      knows the catalog landed but routing still sees the previous snapshot.
+ *   8. Vault credentials sanitisation: api_key / Authorization / Bearer / etc.
+ *      are rejected as field names anywhere in `results.<model>` payloads.
+ *
+ * Other catalog entries are written unchanged (key order preserved) so the
+ * git diff is limited to the `afs` block of patched models.
+ *
+ * Phase 5: weight tables are no longer inlined — the bench provider passes
+ * `loadPolicyWeights` (which the wiring in `bench.ts` resolves through
+ * `/dev/ai/score-weights/<name>`), so this module remains independent of
+ * ai-device internals.
+ */
+interface AFSScores {
+  status: "benchmarked" | "untested" | "deprecated_score";
+  version: string;
+  last_seen_in_run: string;
+  /**
+   * Judge model id(s) used to score `instruction_following`. String for
+   * single-judge runs (back-compat), array for multi-judge ensemble runs
+   * (Phase 0 of Run 4 — plan.md L1052), `null` when no judging happened.
+   */
+  judge: string | string[] | null;
+  samples: number;
+  scores: Record<string, number>;
+  overall: number;
+  policyScores: Record<string, number>;
+  domains?: Record<string, number>;
+}
+interface CatalogEntry {
+  model: string;
+  afs?: AFSScores;
+  [k: string]: unknown;
+}
+interface PatchSummary {
+  changes: Array<{
+    model: string;
+    before: AFSScores | undefined;
+    after: AFSScores;
+  }>;
+  skipped: string[];
+}
+type PolicyWeightsTable = Record<string, Record<string, number>>;
+interface PatchCatalogInput {
+  resultsPath: string;
+  catalogPath: string;
+  resultsRoot: string;
+  /**
+   * Resolve every policy → its weight map. Bench wires this through AFS
+   * (`/dev/ai/score-weights/<name>`), keeping this module free of ai-device
+   * imports. Returning an empty object means no `policyScores` are produced.
+   */
+  loadPolicyWeights: () => Promise<PolicyWeightsTable>;
+  /**
+   * Triggered after the catalog has been atomically written so the device's
+   * registry cache picks the new scores up immediately. Failures propagate —
+   * the catalog already landed, but the caller should know routing still
+   * sees the previous snapshot until the next refresh tick.
+   */
+  refreshRegistry?: () => Promise<void>;
+}
+interface ValidatedResults {
+  version: string;
+  judge_model: string | string[] | null;
+  results: Record<string, ResultEntry>;
+}
+interface ResultEntry {
+  n_samples: number;
+  scores: Record<string, number>;
+  domains?: Record<string, number>;
+}
+/**
+ * Validate raw JSON shape + reject reserved/sensitive keys anywhere.
+ * Throws `ValidationError` on any rejection.
+ *
+ * Layers (in order):
+ *   1. Deep-walk: reject `__proto__` / `constructor` / `prototype` and any
+ *      key matching a credential pattern (`api_key`, `Authorization`, …).
+ *   2. Resource-exhaustion guard: results entries ≤ MAX_RESULT_ENTRIES.
+ *   3. Per-entry whitelist: only `n_samples`/`scores`/`domains`/`stddev`.
+ *   4. Zod schema parse (z.strict() also catches unknown scores dimensions).
+ */
+declare function validateResultsShape(raw: unknown): ValidatedResults;
+/**
+ * Resolve `p` against cwd if relative, then ensure it lives inside `resultsRoot`.
+ * Defends against `..` segments and absolute paths that escape the root.
+ * Returns the absolute path on success; throws `ValidationError` otherwise.
+ *
+ * Note: this is purely lexical (no `fs.realpath`) — a maintainer-created
+ * symlink inside `resultsRoot` pointing outside is not caught here. The threat
+ * model is a maintainer tool, so the lexical check is intentionally cheap; if
+ * a symlink-based vector materialises in production, swap to `fs.realpath`.
+ */
+declare function assertWithinResultsDir(p: string, resultsRoot: string): string;
+/**
+ * Return a deeply-key-sorted clone of an `afs` block. Plain objects get keys
+ * in alphabetical order; arrays preserve order; primitives pass through.
+ * Does not mutate input.
+ */
+declare function sortAfsBlock<T>(value: T): T;
+/** Write `obj` as biome-compatible pretty-printed JSON to `target` via tmp+rename. */
+declare function atomicWriteJSON(target: string, obj: unknown): Promise<void>;
+declare function patchCatalog(input: PatchCatalogInput): Promise<PatchSummary>;
+//#endregion
+export { AFSScores, CatalogEntry, PatchCatalogInput, PatchSummary, PolicyWeightsTable, assertWithinResultsDir, atomicWriteJSON, patchCatalog, sortAfsBlock, validateResultsShape };
+//# sourceMappingURL=patcher.d.cts.map

package/dist/patcher.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patcher.d.cts","names":[],"sources":["../src/patcher.ts"],"mappings":";;AAqCA;;;;;;;;;;;;;;;;;;;;;;AAiBA;;UAjBiB,SAAA;EACf,MAAA;EACA,OAAA;EACA,gBAAA;EAgBM;;;;AAIR;EAdE,KAAA;EACA,OAAA;EACA,MAAA,EAAQ,MAAA;EACR,OAAA;EACA,YAAA,EAAc,MAAA;EACd,OAAA,GAAU,MAAA;AAAA;AAAA,UAGK,YAAA;EACf,KAAA;EACA,GAAA,GAAM,SAAA;EAAA,CACL,CAAA;AAAA;AAAA,UAGc,YAAA;EACf,OAAA,EAAS,KAAA;IAAQ,KAAA;IAAe,MAAA,EAAQ,SAAA;IAAuB,KAAA,EAAO,SAAA;EAAA;EACtE,OAAA;AAAA;AAAA,KAGU,kBAAA,GAAqB,MAAA,SAAe,MAAA;AAAA,UAE/B,iBAAA;EACf,WAAA;EACA,WAAA;EACA,WAAA;EAMiC;;;;;EAAjC,iBAAA,QAAyB,OAAA,CAAQ,kBAAA;EAPjC;;;;;;EAcA,eAAA,SAAwB,OAAA;AAAA;AAAA,UAuGT,gBAAA;EACf,OAAA;EACA,WAAA;EACA,OAAA,EAAS,MAAA,SAAe,WAAA;AAAA;AAAA,UAGhB,WAAA;EACR,SAAA;EACA,MAAA,EAAQ,MAAA;EACR,OAAA,GAAU,MAAA;AAAA;;;AALX;;;;;;;;;iBAmBe,oBAAA,CAAqB,GAAA,YAAe,gBAAA;;AAApD;;;;;AAqEA;;;;iBAAgB,sBAAA,CAAuB,CAAA,UAAW,WAAA;AAiBlD;;;;;AAAA,iBAAgB,YAAA,GAAA,CAAgB,KAAA,EAAO,CAAA,GAAI,CAAA;;iBAoDrB,eAAA,CAAgB,MAAA,UAAgB,GAAA,YAAe,OAAA;AAAA,iBA4C/C,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,OAAA,CAAQ,YAAA"}

package/dist/patcher.d.mts

@@ -0,0 +1,119 @@
+//#region src/patcher.d.ts
+/**
+ * Phase 3 — patchCatalog. Merges a results JSON into the ai-device catalog's
+ * `entry.afs` subtree. Maintainer tool: directly reads/writes catalog.json
+ * (a git-tracked dev artifact, not runtime data) — see decisions.md #24.
+ *
+ * Invariants (plan.md L459-468):
+ *   1. Models missing from results keep their existing `entry.afs` (deep-equal).
+ *   2. Only `r.scores` is copied (no other result fields leak into catalog).
+ *   3. The written `entry.afs` block has alphabetically sorted keys (clean diff).
+ *   4. Atomic write: tmp → rename, no half-written catalog on failure.
+ *   5. Prototype-pollution: __proto__/constructor/prototype rejected anywhere.
+ *   6. Path traversal: resultsPath must resolve inside resultsRoot.
+ *   7. Cache reload via `refreshRegistry` — failures propagate so the caller
+ *      knows the catalog landed but routing still sees the previous snapshot.
+ *   8. Vault credentials sanitisation: api_key / Authorization / Bearer / etc.
+ *      are rejected as field names anywhere in `results.<model>` payloads.
+ *
+ * Other catalog entries are written unchanged (key order preserved) so the
+ * git diff is limited to the `afs` block of patched models.
+ *
+ * Phase 5: weight tables are no longer inlined — the bench provider passes
+ * `loadPolicyWeights` (which the wiring in `bench.ts` resolves through
+ * `/dev/ai/score-weights/<name>`), so this module remains independent of
+ * ai-device internals.
+ */
+interface AFSScores {
+  status: "benchmarked" | "untested" | "deprecated_score";
+  version: string;
+  last_seen_in_run: string;
+  /**
+   * Judge model id(s) used to score `instruction_following`. String for
+   * single-judge runs (back-compat), array for multi-judge ensemble runs
+   * (Phase 0 of Run 4 — plan.md L1052), `null` when no judging happened.
+   */
+  judge: string | string[] | null;
+  samples: number;
+  scores: Record<string, number>;
+  overall: number;
+  policyScores: Record<string, number>;
+  domains?: Record<string, number>;
+}
+interface CatalogEntry {
+  model: string;
+  afs?: AFSScores;
+  [k: string]: unknown;
+}
+interface PatchSummary {
+  changes: Array<{
+    model: string;
+    before: AFSScores | undefined;
+    after: AFSScores;
+  }>;
+  skipped: string[];
+}
+type PolicyWeightsTable = Record<string, Record<string, number>>;
+interface PatchCatalogInput {
+  resultsPath: string;
+  catalogPath: string;
+  resultsRoot: string;
+  /**
+   * Resolve every policy → its weight map. Bench wires this through AFS
+   * (`/dev/ai/score-weights/<name>`), keeping this module free of ai-device
+   * imports. Returning an empty object means no `policyScores` are produced.
+   */
+  loadPolicyWeights: () => Promise<PolicyWeightsTable>;
+  /**
+   * Triggered after the catalog has been atomically written so the device's
+   * registry cache picks the new scores up immediately. Failures propagate —
+   * the catalog already landed, but the caller should know routing still
+   * sees the previous snapshot until the next refresh tick.
+   */
+  refreshRegistry?: () => Promise<void>;
+}
+interface ValidatedResults {
+  version: string;
+  judge_model: string | string[] | null;
+  results: Record<string, ResultEntry>;
+}
+interface ResultEntry {
+  n_samples: number;
+  scores: Record<string, number>;
+  domains?: Record<string, number>;
+}
+/**
+ * Validate raw JSON shape + reject reserved/sensitive keys anywhere.
+ * Throws `ValidationError` on any rejection.
+ *
+ * Layers (in order):
+ *   1. Deep-walk: reject `__proto__` / `constructor` / `prototype` and any
+ *      key matching a credential pattern (`api_key`, `Authorization`, …).
+ *   2. Resource-exhaustion guard: results entries ≤ MAX_RESULT_ENTRIES.
+ *   3. Per-entry whitelist: only `n_samples`/`scores`/`domains`/`stddev`.
+ *   4. Zod schema parse (z.strict() also catches unknown scores dimensions).
+ */
+declare function validateResultsShape(raw: unknown): ValidatedResults;
+/**
+ * Resolve `p` against cwd if relative, then ensure it lives inside `resultsRoot`.
+ * Defends against `..` segments and absolute paths that escape the root.
+ * Returns the absolute path on success; throws `ValidationError` otherwise.
+ *
+ * Note: this is purely lexical (no `fs.realpath`) — a maintainer-created
+ * symlink inside `resultsRoot` pointing outside is not caught here. The threat
+ * model is a maintainer tool, so the lexical check is intentionally cheap; if
+ * a symlink-based vector materialises in production, swap to `fs.realpath`.
+ */
+declare function assertWithinResultsDir(p: string, resultsRoot: string): string;
+/**
+ * Return a deeply-key-sorted clone of an `afs` block. Plain objects get keys
+ * in alphabetical order; arrays preserve order; primitives pass through.
+ * Does not mutate input.
+ */
+declare function sortAfsBlock<T>(value: T): T;
+/** Write `obj` as biome-compatible pretty-printed JSON to `target` via tmp+rename. */
+declare function atomicWriteJSON(target: string, obj: unknown): Promise<void>;
+declare function patchCatalog(input: PatchCatalogInput): Promise<PatchSummary>;
+//#endregion
+export { AFSScores, CatalogEntry, PatchCatalogInput, PatchSummary, PolicyWeightsTable, assertWithinResultsDir, atomicWriteJSON, patchCatalog, sortAfsBlock, validateResultsShape };
+//# sourceMappingURL=patcher.d.mts.map

package/dist/patcher.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patcher.d.mts","names":[],"sources":["../src/patcher.ts"],"mappings":";;AAqCA;;;;;;;;;;;;;;;;;;;;;;AAiBA;;UAjBiB,SAAA;EACf,MAAA;EACA,OAAA;EACA,gBAAA;EAgBM;;;;AAIR;EAdE,KAAA;EACA,OAAA;EACA,MAAA,EAAQ,MAAA;EACR,OAAA;EACA,YAAA,EAAc,MAAA;EACd,OAAA,GAAU,MAAA;AAAA;AAAA,UAGK,YAAA;EACf,KAAA;EACA,GAAA,GAAM,SAAA;EAAA,CACL,CAAA;AAAA;AAAA,UAGc,YAAA;EACf,OAAA,EAAS,KAAA;IAAQ,KAAA;IAAe,MAAA,EAAQ,SAAA;IAAuB,KAAA,EAAO,SAAA;EAAA;EACtE,OAAA;AAAA;AAAA,KAGU,kBAAA,GAAqB,MAAA,SAAe,MAAA;AAAA,UAE/B,iBAAA;EACf,WAAA;EACA,WAAA;EACA,WAAA;EAMiC;;;;;EAAjC,iBAAA,QAAyB,OAAA,CAAQ,kBAAA;EAPjC;;;;;;EAcA,eAAA,SAAwB,OAAA;AAAA;AAAA,UAuGT,gBAAA;EACf,OAAA;EACA,WAAA;EACA,OAAA,EAAS,MAAA,SAAe,WAAA;AAAA;AAAA,UAGhB,WAAA;EACR,SAAA;EACA,MAAA,EAAQ,MAAA;EACR,OAAA,GAAU,MAAA;AAAA;;;AALX;;;;;;;;;iBAmBe,oBAAA,CAAqB,GAAA,YAAe,gBAAA;;AAApD;;;;;AAqEA;;;;iBAAgB,sBAAA,CAAuB,CAAA,UAAW,WAAA;AAiBlD;;;;;AAAA,iBAAgB,YAAA,GAAA,CAAgB,KAAA,EAAO,CAAA,GAAI,CAAA;;iBAoDrB,eAAA,CAAgB,MAAA,UAAgB,GAAA,YAAe,OAAA;AAAA,iBA4C/C,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,OAAA,CAAQ,YAAA"}