/**
 * Validator types for the MCP schema runtime hook.
 *
 * The MCP server stays schema-agnostic at the type level: it loads
 * JSON Schema bundles (data) at boot, never imports a live Zod registry.
 * This file declares only the shape of the validator, not how it's built.
 */

export interface MetaValidationIssue {
	/** JSON-pointer-ish path to the offending field, e.g. "/priority". */
	readonly path: string;
	/** Human-readable error message. */
	readonly message: string;
	/** Ajv keyword that failed (e.g. "enum", "required", "pattern"). */
	readonly keyword?: string;
}

export type MetaValidationResult =
	| { ok: true }
	| { ok: false; errors: ReadonlyArray<MetaValidationIssue> };

export interface SchemaBundleValidator {
	/** Doc-types known to this bundle. */
	readonly knownTypes: ReadonlyArray<string>;
	/**
	 * Validate `meta` against the schema for `docType`. If `docType` is not
	 * in this bundle, returns `{ ok: true }` — unknown doc-types are
	 * unconstrained (Rule 4: never reject existing-app traffic).
	 */
	validateMeta(docType: string, meta: unknown): MetaValidationResult;
}
