@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/registry/custom.ts

@@ -0,0 +1,431 @@
+import type { CustomTypeConfig } from "../schemas/config.ts";
+import {
+	compactMeta,
+	formatLinks,
+	formatOutcome,
+	formatRecordMeta,
+	idTag,
+	truncate,
+	xmlEscape,
+} from "../utils/format-helpers.ts";
+import { BUILTIN_DEFS } from "./builtins.ts";
+import { compileSummaryTemplate, extractTemplateTokens } from "./template.ts";
+import type { TypeDefinition } from "./type-registry.ts";
+
+const BUILTIN_DEFS_BY_NAME: ReadonlyMap<string, TypeDefinition> = new Map(
+	BUILTIN_DEFS.map((d) => [d.name, d]),
+);
+
+export const BUILTIN_TYPE_NAMES: ReadonlySet<string> = new Set([
+	"convention",
+	"pattern",
+	"failure",
+	"decision",
+	"reference",
+	"guide",
+]);
+
+// Fields owned by BaseRecord. Custom types must NOT redeclare these as
+// required/optional — they're applied automatically by the schema layer.
+const BASE_FIELDS: ReadonlySet<string> = new Set([
+	"id",
+	"type",
+	"classification",
+	"recorded_at",
+	"evidence",
+	"tags",
+	"relates_to",
+	"supersedes",
+	"outcomes",
+]);
+
+const CUSTOM_NAME_RE = /^[a-z][a-z0-9_]*$/;
+const NAMING_RULE =
+	"lowercase letters, digits, and underscores; must start with a letter; no hyphens";
+
+// Required + optional fields owned by built-in types. Used to reject custom
+// type aliases whose legacy name collides with a foreign type's field — that
+// would silently swallow a field name another type relies on.
+const BUILTIN_FIELDS: ReadonlySet<string> = new Set(
+	BUILTIN_DEFS.flatMap((d) => [...d.required, ...d.optional]),
+);
+
+function describeNameViolation(value: string): string {
+	if (value.length === 0) return "must not be empty";
+	if (value.includes("-")) return "contains a hyphen";
+	if (/^\d/.test(value)) return "starts with a digit";
+	if (!/^[a-z]/.test(value)) return "must start with a lowercase letter";
+	if (/[A-Z]/.test(value)) return "contains uppercase letters";
+	if (/[^a-z0-9_]/.test(value)) return "contains a character outside [a-z0-9_]";
+	return "violates the naming rule";
+}
+
+const VALID_COMPACT_STRATEGIES = new Set(["concat", "merge_outcomes", "keep_latest", "manual"]);
+
+const linkArray = {
+	type: "array",
+	items: { type: "string", pattern: "^([a-z0-9-]+:)?mx-[0-9a-f]{4,8}$" },
+} as const;
+
+export function validateCustomTypeConfig(name: string, cfg: CustomTypeConfig): void {
+	if (!CUSTOM_NAME_RE.test(name)) {
+		throw new Error(
+			`Invalid custom_types name "${name}" (${describeNameViolation(name)}). Allowed: ${NAMING_RULE}.`,
+		);
+	}
+	if (BUILTIN_TYPE_NAMES.has(name)) {
+		throw new Error(
+			`Custom type "${name}" shadows a built-in record type. Reserved names: ${[...BUILTIN_TYPE_NAMES].join(", ")}.`,
+		);
+	}
+
+	let parent: TypeDefinition | undefined;
+	if (cfg.extends !== undefined) {
+		if (typeof cfg.extends !== "string" || cfg.extends.length === 0) {
+			throw new Error(`Custom type "${name}" extends must be a non-empty string.`);
+		}
+		if (!BUILTIN_TYPE_NAMES.has(cfg.extends)) {
+			throw new Error(
+				`Custom type "${name}" extends "${cfg.extends}" must be a built-in type. Built-ins: ${[...BUILTIN_TYPE_NAMES].join(", ")}. Custom-from-custom inheritance is not supported in v1.`,
+			);
+		}
+		parent = BUILTIN_DEFS_BY_NAME.get(cfg.extends);
+	}
+
+	const childRequired = cfg.required ?? [];
+	if (!parent && childRequired.length === 0) {
+		throw new Error(
+			`Custom type "${name}" must declare a non-empty "required" array (or set "extends" to inherit from a built-in).`,
+		);
+	}
+
+	// Track child-only declarations separately from the merged set: a child
+	// may redundantly redeclare a parent field (union semantics — silent), but
+	// must not declare the same field twice within its own config.
+	const childSeen = new Set<string>();
+	const mergedSeen = new Set<string>();
+	if (parent) {
+		for (const f of parent.required) mergedSeen.add(f);
+		for (const f of parent.optional) mergedSeen.add(f);
+	}
+
+	for (const f of childRequired) {
+		if (typeof f !== "string" || f.length === 0) {
+			throw new Error(`Custom type "${name}" has an invalid required field: ${JSON.stringify(f)}.`);
+		}
+		if (!CUSTOM_NAME_RE.test(f)) {
+			throw new Error(
+				`Custom type "${name}" required field "${f}" (${describeNameViolation(f)}). Allowed: ${NAMING_RULE}.`,
+			);
+		}
+		if (BASE_FIELDS.has(f)) {
+			throw new Error(
+				`Custom type "${name}" cannot declare base field "${f}" as required (base fields: ${[...BASE_FIELDS].join(", ")}).`,
+			);
+		}
+		if (childSeen.has(f)) {
+			throw new Error(`Custom type "${name}" has duplicate required field "${f}".`);
+		}
+		childSeen.add(f);
+		mergedSeen.add(f);
+	}
+	for (const f of cfg.optional ?? []) {
+		if (typeof f !== "string" || f.length === 0) {
+			throw new Error(`Custom type "${name}" has an invalid optional field: ${JSON.stringify(f)}.`);
+		}
+		if (!CUSTOM_NAME_RE.test(f)) {
+			throw new Error(
+				`Custom type "${name}" optional field "${f}" (${describeNameViolation(f)}). Allowed: ${NAMING_RULE}.`,
+			);
+		}
+		if (BASE_FIELDS.has(f)) {
+			throw new Error(`Custom type "${name}" cannot declare base field "${f}" as optional.`);
+		}
+		if (childSeen.has(f)) {
+			throw new Error(`Custom type "${name}" has field "${f}" in both required and optional.`);
+		}
+		childSeen.add(f);
+		mergedSeen.add(f);
+	}
+
+	const effectiveDedupKey = cfg.dedup_key ?? parent?.dedupKey;
+	if (typeof effectiveDedupKey !== "string" || effectiveDedupKey.length === 0) {
+		throw new Error(
+			`Custom type "${name}" must set "dedup_key" (field name or "content_hash"), or extend a built-in that defines one.`,
+		);
+	}
+	if (effectiveDedupKey !== "content_hash" && !mergedSeen.has(effectiveDedupKey)) {
+		throw new Error(
+			`Custom type "${name}" dedup_key "${effectiveDedupKey}" must be declared in required/optional or be "content_hash".`,
+		);
+	}
+	if (cfg.id_key !== undefined && cfg.id_key !== "content_hash" && !mergedSeen.has(cfg.id_key)) {
+		throw new Error(
+			`Custom type "${name}" id_key "${cfg.id_key}" must be declared in required/optional or be "content_hash".`,
+		);
+	}
+	if (cfg.summary === undefined && !parent) {
+		throw new Error(`Custom type "${name}" must set "summary" template string.`);
+	}
+	if (cfg.summary !== undefined && (typeof cfg.summary !== "string" || cfg.summary.length === 0)) {
+		throw new Error(`Custom type "${name}" "summary" must be a non-empty string.`);
+	}
+	if (typeof cfg.summary === "string") {
+		// Reject `{tok}` references that won't resolve at render time. Without
+		// this, a typo (e.g. {description} on a type whose required field is
+		// `content`) renders as empty string in `lm prime` output, silently
+		// degrading every record of that type.
+		const validTokens = new Set<string>([...BASE_FIELDS, ...mergedSeen]);
+		for (const token of extractTemplateTokens(cfg.summary)) {
+			if (!validTokens.has(token)) {
+				const known = [...validTokens].sort().join(", ");
+				throw new Error(
+					`Custom type "${name}" summary references unknown field "{${token}}". Declared fields: ${known}.`,
+				);
+			}
+		}
+	}
+	if (cfg.compact !== undefined && !VALID_COMPACT_STRATEGIES.has(cfg.compact)) {
+		throw new Error(
+			`Custom type "${name}" compact strategy "${cfg.compact}" is invalid. Use one of: ${[...VALID_COMPACT_STRATEGIES].join(", ")}.`,
+		);
+	}
+	if (cfg.extracts_files && cfg.files_field !== undefined && !mergedSeen.has(cfg.files_field)) {
+		throw new Error(
+			`Custom type "${name}" files_field "${cfg.files_field}" must be declared in required/optional when extracts_files: true.`,
+		);
+	}
+	if (cfg.aliases !== undefined) {
+		if (typeof cfg.aliases !== "object" || cfg.aliases === null || Array.isArray(cfg.aliases)) {
+			throw new Error(
+				`Custom type "${name}" aliases must be a map of canonical field name → legacy alias names.`,
+			);
+		}
+		const seenAliases = new Set<string>();
+		for (const [canonical, legacyNames] of Object.entries(cfg.aliases)) {
+			if (!mergedSeen.has(canonical)) {
+				throw new Error(
+					`Custom type "${name}" aliases key "${canonical}" must be declared in required/optional.`,
+				);
+			}
+			if (!Array.isArray(legacyNames) || legacyNames.length === 0) {
+				throw new Error(
+					`Custom type "${name}" aliases entry "${canonical}" must be a non-empty array of legacy field names.`,
+				);
+			}
+			for (const legacy of legacyNames) {
+				if (typeof legacy !== "string" || legacy.length === 0) {
+					throw new Error(
+						`Custom type "${name}" aliases entry "${canonical}" has an invalid legacy name: ${JSON.stringify(legacy)}.`,
+					);
+				}
+				if (!CUSTOM_NAME_RE.test(legacy)) {
+					throw new Error(
+						`Custom type "${name}" aliases legacy name "${legacy}" (${describeNameViolation(legacy)}). Allowed: ${NAMING_RULE}.`,
+					);
+				}
+				if (BASE_FIELDS.has(legacy)) {
+					throw new Error(
+						`Custom type "${name}" aliases legacy name "${legacy}" collides with a base field.`,
+					);
+				}
+				// Reject aliases legacy name that names a built-in type's field.
+				// Aliases run at read time only on records of *this* type, so a
+				// foreign-field name on disk isn't actively confused — but
+				// declaring one signals a misunderstanding (the user thinks the
+				// field is theirs when it belongs to another type) and tends to
+				// surface as silent loss when records get reclassified.
+				if (BUILTIN_FIELDS.has(legacy) && !mergedSeen.has(legacy)) {
+					throw new Error(
+						`Custom type "${name}" aliases legacy name "${legacy}" collides with a built-in type's field. Use a name that isn't already owned by another type, or set it as required/optional on this type if the field really belongs here.`,
+					);
+				}
+				if (mergedSeen.has(legacy)) {
+					throw new Error(
+						`Custom type "${name}" aliases legacy name "${legacy}" is already declared as a current field; aliases are for retired names only.`,
+					);
+				}
+				if (seenAliases.has(legacy)) {
+					throw new Error(
+						`Custom type "${name}" aliases legacy name "${legacy}" appears under multiple canonical fields; each alias maps to one canonical name.`,
+					);
+				}
+				seenAliases.add(legacy);
+			}
+		}
+	}
+}
+
+function defaultSectionTitle(name: string): string {
+	return `${name.charAt(0).toUpperCase() + name.slice(1)}s`;
+}
+
+function mergeFieldList(
+	parentFields: readonly string[] | undefined,
+	childFields: readonly string[] | undefined,
+): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const f of parentFields ?? []) {
+		if (!seen.has(f)) {
+			seen.add(f);
+			out.push(f);
+		}
+	}
+	for (const f of childFields ?? []) {
+		if (!seen.has(f)) {
+			seen.add(f);
+			out.push(f);
+		}
+	}
+	return out;
+}
+
+export function getBuiltinTypeDef(name: string): TypeDefinition | undefined {
+	return BUILTIN_DEFS_BY_NAME.get(name);
+}
+
+export function buildCustomTypeDefinition(name: string, cfg: CustomTypeConfig): TypeDefinition {
+	validateCustomTypeConfig(name, cfg);
+
+	const parent = cfg.extends ? BUILTIN_DEFS_BY_NAME.get(cfg.extends) : undefined;
+
+	// Union the field arrays parent-first so inherited fields keep their
+	// declared order, with the child's own fields appended.
+	const required = mergeFieldList(parent?.required, cfg.required);
+	// A child can promote a parent's optional field by listing it under
+	// `required`. Strip those from the optional list so the field doesn't
+	// appear in both arrays.
+	const requiredSet = new Set(required);
+	const optional = mergeFieldList(parent?.optional, cfg.optional).filter(
+		(f) => !requiredSet.has(f),
+	);
+
+	const dedupKey = cfg.dedup_key ?? parent?.dedupKey ?? "content_hash";
+	const idKey = cfg.id_key ?? cfg.dedup_key ?? parent?.idKey ?? dedupKey;
+	const summaryFn = cfg.summary
+		? compileSummaryTemplate(cfg.summary)
+		: (parent?.summary ?? (() => ""));
+	const extractsFiles = cfg.extracts_files ?? parent?.extractsFiles ?? false;
+	const filesField = cfg.files_field ?? parent?.filesField ?? "files";
+	const compactStrategy = cfg.compact ?? parent?.compact ?? "manual";
+	const sectionTitle = cfg.section_title ?? parent?.sectionTitle ?? defaultSectionTitle(name);
+
+	const properties: Record<string, unknown> = {
+		id: { type: "string", pattern: "^mx-[0-9a-f]{4,8}$" },
+		type: { type: "string", const: name },
+		classification: { $ref: "#/definitions/classification" },
+		recorded_at: { type: "string" },
+		evidence: { $ref: "#/definitions/evidence" },
+		tags: { type: "array", items: { type: "string" } },
+		relates_to: linkArray,
+		supersedes: linkArray,
+		outcomes: { type: "array", items: { $ref: "#/definitions/outcome" } },
+		dir_anchors: { type: "array", items: { type: "string" } },
+		supersession_demoted_at: { type: "string" },
+		anchor_decay_demoted_at: { type: "string" },
+		owner: { type: "string" },
+		status: { type: "string", enum: ["draft", "active", "deprecated"] },
+	};
+
+	for (const f of [...required, ...optional]) {
+		if (extractsFiles && f === filesField) {
+			properties[f] = { type: "array", items: { type: "string" } };
+		} else {
+			properties[f] = { type: "string" };
+		}
+	}
+
+	const ajvSchema = {
+		type: "object",
+		properties,
+		required: ["type", ...required, "classification", "recorded_at"],
+		additionalProperties: false,
+	};
+
+	const aliases = cfg.aliases
+		? Object.fromEntries(Object.entries(cfg.aliases).map(([k, v]) => [k, [...v]]))
+		: undefined;
+
+	return {
+		name,
+		kind: "custom",
+		required,
+		optional,
+		dedupKey,
+		idKey,
+		summary: summaryFn,
+		extractsFiles,
+		filesField,
+		compact: compactStrategy,
+		sectionTitle,
+		ajvSchema,
+		...(aliases ? { aliases } : {}),
+		formatMarkdown: (records, full) => {
+			if (records.length === 0) return "";
+			const lines = [`### ${sectionTitle}`];
+			for (const rec of records) {
+				const r = rec as unknown as Record<string, unknown>;
+				let line = `- ${idTag(rec)}**${summaryFn(rec)}**`;
+				const detail: string[] = [];
+				for (const f of [...required, ...optional]) {
+					if (extractsFiles && f === filesField) continue;
+					const v = r[f];
+					if (v == null || v === "") continue;
+					detail.push(`${f}: ${String(v)}`);
+				}
+				if (detail.length > 0) line += ` — ${detail.join("; ")}`;
+				if (extractsFiles) {
+					const files = r[filesField];
+					if (Array.isArray(files) && files.length > 0) {
+						line += ` (${(files as string[]).join(", ")})`;
+					}
+				}
+				line += formatRecordMeta(rec, full);
+				lines.push(line);
+			}
+			return lines.join("\n");
+		},
+		formatCompactLine: (record) => {
+			const r = record as unknown as Record<string, unknown>;
+			const links = formatLinks(record);
+			const meta = compactMeta(record);
+			const outcome = formatOutcome(record.outcomes);
+			let filesPart = "";
+			if (extractsFiles) {
+				const files = r[filesField];
+				if (Array.isArray(files) && files.length > 0) {
+					filesPart = ` (${(files as string[]).join(", ")})`;
+				}
+			}
+			return `- [${name}] ${truncate(summaryFn(record))}${filesPart}${meta}${outcome}${links}`;
+		},
+		formatXml: (record) => {
+			const r = record as unknown as Record<string, unknown>;
+			const lines: string[] = [];
+			for (const f of [...required, ...optional]) {
+				const v = r[f];
+				if (v == null) continue;
+				if (Array.isArray(v)) {
+					lines.push(
+						`    <${f}>${(v as string[]).map((s) => xmlEscape(String(s))).join(", ")}</${f}>`,
+					);
+				} else {
+					lines.push(`    <${f}>${xmlEscape(String(v))}</${f}>`);
+				}
+			}
+			return lines;
+		},
+	};
+}
+
+export function buildCustomTypeDefinitions(
+	customTypes: Record<string, CustomTypeConfig> | undefined,
+): TypeDefinition[] {
+	if (!customTypes) return [];
+	const defs: TypeDefinition[] = [];
+	for (const [name, cfg] of Object.entries(customTypes)) {
+		defs.push(buildCustomTypeDefinition(name, cfg));
+	}
+	return defs;
+}

package/src/tools/loam/registry/init.ts

@@ -0,0 +1,55 @@
+import type { LoamConfig } from "../schemas/config.ts";
+import { readConfig } from "../utils/config.ts";
+import { BUILTIN_DEFS, buildBuiltinRegistry } from "./builtins.ts";
+import { buildCustomTypeDefinitions } from "./custom.ts";
+import {
+	setRegistry,
+	type TypeRegistry,
+	TypeRegistry as TypeRegistryCtor,
+} from "./type-registry.ts";
+
+// Hoist SHARED_DEFINITIONS through buildBuiltinRegistry to keep one source of
+// truth. We construct a temporary builtin registry just to read its definitions.
+function buildRegistryWithCustomTypes(config: LoamConfig | null): TypeRegistry {
+	const disabled = config?.disabled_types ?? [];
+	if (config?.custom_types && disabled.length > 0) {
+		const disabledSet = new Set(disabled);
+		for (const [childName, childCfg] of Object.entries(config.custom_types)) {
+			if (childCfg.extends && disabledSet.has(childCfg.extends)) {
+				throw new Error(
+					`Custom type "${childName}" extends "${childCfg.extends}", which is in disabled_types. Re-enable the parent or remove the extends clause.`,
+				);
+			}
+		}
+	}
+
+	const customDefs = config?.custom_types ? buildCustomTypeDefinitions(config.custom_types) : [];
+	const allDefs = customDefs.length === 0 ? [...BUILTIN_DEFS] : [...BUILTIN_DEFS, ...customDefs];
+	const knownNames = new Set(allDefs.map((d) => d.name));
+
+	for (const name of disabled) {
+		if (!knownNames.has(name)) {
+			throw new Error(
+				`disabled_types references unregistered type "${name}". Declare it under custom_types or remove it from disabled_types.`,
+			);
+		}
+	}
+
+	const builtinRegistry = buildBuiltinRegistry();
+	return new TypeRegistryCtor(allDefs, builtinRegistry.definitions, disabled);
+}
+
+// Called once at CLI startup. Falls back to built-ins-only if no config exists
+// (e.g., before `lm init`) so commands like `lm init` still work.
+export async function initRegistryFromConfig(cwd?: string): Promise<TypeRegistry> {
+	let config: LoamConfig | null = null;
+	try {
+		config = await readConfig(cwd);
+	} catch {
+		// No .loam/ directory or unreadable config — built-ins only.
+		config = null;
+	}
+	const registry = buildRegistryWithCustomTypes(config);
+	setRegistry(registry);
+	return registry;
+}

package/src/tools/loam/registry/template.ts

@@ -0,0 +1,40 @@
+import type { ExpertiseRecord } from "../schemas/record.ts";
+
+// Interpolation only — no conditionals, fallbacks, or transforms in v1 (per
+// epic loam-632e locked design). Both `{field}` and `{{field}}` are accepted
+// because Mustache-style is muscle memory; the double-brace branch is matched
+// first so it's preferred over the single-brace fallback.
+const TOKEN_RE = /\{\{([a-z_][a-z0-9_]*)\}\}|\{([a-z_][a-z0-9_]*)\}/gi;
+
+export function extractTemplateTokens(template: string): string[] {
+	const tokens: string[] = [];
+	for (const match of template.matchAll(TOKEN_RE)) {
+		const token = match[1] ?? match[2];
+		if (token) tokens.push(token);
+	}
+	return tokens;
+}
+
+export function compileSummaryTemplate(template: string): (record: ExpertiseRecord) => string {
+	const tokens: string[] = [];
+	const literals: string[] = [];
+	let lastIndex = 0;
+	for (const match of template.matchAll(TOKEN_RE)) {
+		const start = match.index ?? 0;
+		literals.push(template.slice(lastIndex, start));
+		tokens.push(match[1] ?? match[2] ?? "");
+		lastIndex = start + match[0].length;
+	}
+	literals.push(template.slice(lastIndex));
+
+	return (record: ExpertiseRecord): string => {
+		let out = literals[0] ?? "";
+		for (let i = 0; i < tokens.length; i++) {
+			const token = tokens[i] ?? "";
+			const value = (record as unknown as Record<string, unknown>)[token];
+			out += value == null ? "" : String(value);
+			out += literals[i + 1] ?? "";
+		}
+		return out;
+	};
+}

package/src/tools/loam/registry/type-registry.ts

@@ -0,0 +1,113 @@
+import Ajv, { type ValidateFunction } from "ajv";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { buildBuiltinRegistry } from "./builtins.ts";
+
+export interface TypeDefinition {
+	name: string;
+	kind: "builtin" | "custom";
+	required: readonly string[];
+	optional: readonly string[];
+	dedupKey: string | "content_hash";
+	idKey: string;
+	summary: (record: ExpertiseRecord) => string;
+	extractsFiles: boolean;
+	filesField: string;
+	compact: "keep_latest" | "concat" | "merge_outcomes" | "manual";
+	sectionTitle: string;
+	ajvSchema: Record<string, unknown>;
+	formatMarkdown: (records: ExpertiseRecord[], full: boolean) => string;
+	formatCompactLine: (record: ExpertiseRecord) => string;
+	formatXml: (record: ExpertiseRecord) => string[];
+	// Phase 3: canonical field name → legacy aliases. Only set on custom types.
+	aliases?: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface SharedDefinitions {
+	classification: Record<string, unknown>;
+	evidence: Record<string, unknown>;
+	outcome: Record<string, unknown>;
+}
+
+export class TypeRegistry {
+	readonly definitions: SharedDefinitions;
+	private readonly defs: ReadonlyMap<string, TypeDefinition>;
+	private readonly order: readonly string[];
+	private readonly disabledSet: ReadonlySet<string>;
+	readonly validator: ValidateFunction;
+
+	constructor(
+		defs: TypeDefinition[],
+		definitions: SharedDefinitions,
+		disabled: Iterable<string> = [],
+	) {
+		this.defs = new Map(defs.map((d) => [d.name, d]));
+		this.order = defs.map((d) => d.name);
+		this.disabledSet = new Set(disabled);
+		this.definitions = definitions;
+		this.validator = compileValidator(defs, definitions);
+	}
+
+	get(name: string): TypeDefinition | undefined {
+		return this.defs.get(name);
+	}
+
+	enabled(): TypeDefinition[] {
+		return this.order.map((n) => this.defs.get(n) as TypeDefinition);
+	}
+
+	names(): string[] {
+		return [...this.order];
+	}
+
+	isDisabled(name: string): boolean {
+		return this.disabledSet.has(name);
+	}
+
+	disabledNames(): string[] {
+		return [...this.disabledSet];
+	}
+
+	builtinDefs(): TypeDefinition[] {
+		return this.enabled().filter((d) => d.kind === "builtin");
+	}
+
+	customDefs(): TypeDefinition[] {
+		return this.enabled().filter((d) => d.kind === "custom");
+	}
+}
+
+function compileValidator(
+	defs: TypeDefinition[],
+	definitions: SharedDefinitions,
+): ValidateFunction {
+	const schema = {
+		$schema: "http://json-schema.org/draft-07/schema#",
+		title: "Loam Expertise Record",
+		description: "A single expertise record in a Loam domain file",
+		type: "object",
+		definitions,
+		oneOf: defs.map((d) => d.ajvSchema),
+	};
+	const ajv = new Ajv();
+	return ajv.compile(schema);
+}
+
+let _registry: TypeRegistry | null = null;
+
+// Lazy fallback to a built-in registry so callers (api.ts, tests) that don't
+// explicitly initialize still get a working registry. CLI/entry points may
+// call setRegistry() to override (e.g., Phase 2's config-derived custom types).
+export function getRegistry(): TypeRegistry {
+	if (!_registry) {
+		_registry = buildBuiltinRegistry();
+	}
+	return _registry;
+}
+
+export function setRegistry(registry: TypeRegistry): void {
+	_registry = registry;
+}
+
+export function resetRegistry(): void {
+	_registry = null;
+}