@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/src/meta-spec.ts

@@ -1,718 +0,0 @@
-/**
- * Codegen-time policy engine: route meta + route schemas → OpenAPI operation fields.
- * Never consulted at request time. See docs/meta-spec.md.
- */
-import type {
-	MetaSpecConfig,
-	MetaSpecContext,
-	MetaSpecEntry,
-	MetaSpecProfile,
-	MetaSpecSchemaEntry,
-	MetaSpecSchemaSearch,
-	MetaSpecSchemaSource,
-	MetaSpecStrictness,
-	MetaSpecVersionGuard,
-	StandardSchemaLike,
-} from "./types.ts"
-import { resolvedStrictness } from "./meta-spec-merge.ts"
-
-export { mergeMetaSpec, resolvedStrictness } from "./meta-spec-merge.ts"
-
-/* ---- constants ---- */
-
-/** Standard operation fields a policy may target */
-const ALLOWED_STANDARD_FIELDS = new Set([
-	"deprecated",
-	"description",
-	"externalDocs",
-	"operationId",
-	"security",
-	"servers",
-	"summary",
-	"tags",
-])
-
-/** Derived from schemas and error keys — a policy that wrote these would contradict the route */
-const RESERVED_FIELDS = new Set(["callbacks", "parameters", "requestBody", "responses"])
-
-const SCHEMA_SOURCES: readonly MetaSpecSchemaSource[] = [
-	"output",
-	"input.json",
-	"input.search",
-	"input.form",
-	"input.headers",
-	"input.cookies",
-]
-
-export const DEFAULT_PROFILE = "default"
-
-/* ---- security shorthand ---- */
-
-/**
- * Normalize security shorthand → standard OpenAPI security array.
- *
- * `"jwt"`, `["jwt", "apiKey"]` (alternatives), `[["key", "domain"]]` (all of a group) and the
- * standard `[{ jwt: [] }]` form are accepted. `[]` is an explicit "no authentication". Anything
- * else throws: guessing would turn a protected route into a documented public one.
- */
-export function normalizeSecurity(raw: unknown): Record<string, string[]>[] {
-	if (typeof raw === "string") {
-		if (raw === "") throw new TypeError("security: a scheme name cannot be empty")
-		return [{ [raw]: [] }]
-	}
-	if (!Array.isArray(raw)) throw new TypeError(`security: expected a scheme name or an array, got ${describe(raw)}`)
-	if (raw.length === 0) return []
-	if (raw.every((entry) => typeof entry === "string" && entry !== "")) {
-		return (raw as string[]).map((entry) => ({ [entry]: [] }))
-	}
-	if (raw.every((entry) => Array.isArray(entry) && entry.every((s) => typeof s === "string" && s !== ""))) {
-		return (raw as string[][]).map((group) => Object.fromEntries(group.map((s) => [s, []])))
-	}
-	if (raw.every(isRequirement)) {
-		return raw as Record<string, string[]>[]
-	}
-	throw new TypeError(
-		"security: entries must all be scheme names, all be groups of scheme names, or all be " +
-			"{ scheme: scopes[] } requirement objects — mixed or malformed entries are refused",
-	)
-}
-
-function isRequirement(entry: unknown): boolean {
-	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false
-	for (const [name, scopes] of Object.entries(entry)) {
-		if (name === "") return false
-		if (!Array.isArray(scopes) || !scopes.every((s) => typeof s === "string")) return false
-	}
-	return true
-}
-
-function describe(value: unknown): string {
-	if (value === null) return "null"
-	if (Array.isArray(value)) return "an array"
-	return typeof value
-}
-
-/** Scheme names an operation's `security` refers to. */
-export function securitySchemeNames(security: unknown): string[] {
-	if (!Array.isArray(security)) return []
-	const names = new Set<string>()
-	for (const requirement of security) {
-		if (requirement === null || typeof requirement !== "object") continue
-		for (const name of Object.keys(requirement)) names.add(name)
-	}
-	return [...names]
-}
-
-/** `invalidate` selectors, deduplicated in first-seen order. */
-function uniqueSelectors(value: unknown[]): unknown[] {
-	return [...new Set(value)]
-}
-
-/* ---- diagnostics ---- */
-
-export type MetaSpecDiagnosticCode =
-	| "AMBIGUOUS_SCHEMA_KEY"
-	| "ASYNC_VALIDATION"
-	| "DESCRIPTOR_MISMATCH"
-	| "SUBAPP_ENTRY_CONFLICT"
-	| "DUPLICATE_OPERATION_ID"
-	| "DUPLICATE_TARGET"
-	| "INVALID_SELECTOR"
-	| "INVALID_VALUE"
-	| "MAP_THREW"
-	| "MISSING_ENTRY"
-	| "RESERVED_FIELD"
-	| "UNKNOWN_FIELD"
-	| "UNKNOWN_PROFILE"
-	| "UNKNOWN_SECURITY_SCHEME"
-	| "UNSUPPORTED_METHOD"
-	| "UNSUPPORTED_VERSION"
-	| "WS_SHADOWED"
-
-export type MetaSpecDiagnostic = {
-	code: MetaSpecDiagnosticCode
-	level: "error" | "warn"
-	message: string
-}
-
-export class MetaSpecCollector {
-	readonly diagnostics: MetaSpecDiagnostic[] = []
-	/** Meta keys already reported as unmapped — reported once, not once per route */
-	readonly reportedMissing = new Set<string>()
-	private readonly seen = new Set<string>()
-
-	add(code: MetaSpecDiagnosticCode, level: "error" | "warn", message: string): void {
-		const dedupeKey = `${code}\u0000${message}`
-		if (this.seen.has(dedupeKey)) return
-		this.seen.add(dedupeKey)
-		this.diagnostics.push({ code, level, message })
-	}
-
-	/** Throws one aggregated error if anything failed; warnings go to the console. */
-	flush(): void {
-		const errors = this.diagnostics.filter((d) => d.level === "error")
-		const warnings = this.diagnostics.filter((d) => d.level === "warn")
-		for (const w of warnings) {
-			console.warn(`[honey:metaSpec] ${w.code}: ${w.message}`)
-		}
-		if (errors.length === 0) return
-		const shown = errors.slice(0, 20).map((e) => `  - ${e.code}: ${e.message}`)
-		const more = errors.length > shown.length ? `\n  … and ${errors.length - shown.length} more` : ""
-		throw new Error(`[honey:metaSpec] ${errors.length} policy error(s):\n${shown.join("\n")}${more}`)
-	}
-}
-
-/* ---- compiled policy ---- */
-
-type Produce = (value: unknown, ctx: MetaSpecContext) => Record<string, unknown> | undefined
-
-type CompiledEntry = {
-	/** Meta key, or schema-metadata key for schema entries */
-	from: readonly MetaSpecSchemaSource[] | null
-	http: boolean
-	/** Declared target keys, for same-rank duplicate detection. Empty for `expand` entries */
-	keys: readonly string[]
-	produce: Produce
-	profiles: readonly string[] | null
-	match: Record<string, unknown> | null
-	rank: 1 | 2
-	/** Schema-metadata key this entry reads; defaults to `sourceKey` */
-	read: string
-	schema: StandardSchemaLike | null
-	search: MetaSpecSchemaSearch
-	version: MetaSpecVersionGuard | null
-	sourceKey: string
-	ws: boolean
-}
-
-export type CompiledMetaSpec = {
-	entries: readonly CompiledEntry[]
-	/** Meta keys with an entry (or deliberately hidden) — used for the totality check */
-	known: ReadonlySet<string>
-	needsSchemas: boolean
-	profiles: Record<string, MetaSpecProfile>
-	strict: MetaSpecStrictness
-}
-
-function truthy(key: string): Produce {
-	return (value) => (value ? { [key]: value } : undefined)
-}
-
-/** The eight pre-policy mappings, verbatim, in their original emit order. */
-function builtinEntries(): CompiledEntry[] {
-	const mk = (
-		sourceKey: string,
-		key: string,
-		produce: Produce,
-		opts: { http?: boolean; ws?: boolean } = {},
-	): CompiledEntry => ({
-		from: null,
-		http: opts.http ?? true,
-		keys: [key],
-		match: null,
-		produce,
-		profiles: null,
-		/* built-ins are route meta too — same precedence tier as app meta entries */
-		rank: 2,
-		read: sourceKey,
-		schema: null,
-		search: "root",
-		sourceKey,
-		version: null,
-		ws: opts.ws ?? false,
-	})
-
-	return [
-		mk("summary", "summary", truthy("summary"), { ws: true }),
-		mk("description", "description", truthy("description"), { ws: true }),
-		mk("tags", "tags", (v) => (v ? { tags: typeof v === "string" ? [v] : v } : undefined), { ws: true }),
-		mk("deprecated", "deprecated", truthy("deprecated")),
-		mk("operationId", "operationId", truthy("operationId"), { ws: true }),
-		mk("security", "security", (v) => (v ? { security: normalizeSecurity(v) } : undefined)),
-		mk("invalidate", "x-invalidate", (v) =>
-			Array.isArray(v) && v.length > 0 ? { "x-invalidate": uniqueSelectors(v) } : undefined,
-		),
-		mk("mcp", "x-mcp", (v) => (v === true ? { "x-mcp": true } : undefined)),
-	]
-}
-
-/** Meta keys that never reach the document even without an app policy. */
-const BUILTIN_HIDDEN = ["internal", "extensions"]
-
-function targetFlags(on: string | undefined): { http: boolean; ws: boolean } {
-	if (on === "http") return { http: true, ws: false }
-	if (on === "ws") return { http: false, ws: true }
-	return { http: true, ws: true }
-}
-
-function checkTargetKey(key: string, where: string, collector: MetaSpecCollector): boolean {
-	if (key.startsWith("x-")) return true
-	if (RESERVED_FIELDS.has(key)) {
-		collector.add("RESERVED_FIELD", "error", `${where} targets reserved operation field "${key}"`)
-		return false
-	}
-	if (!ALLOWED_STANDARD_FIELDS.has(key)) {
-		collector.add(
-			"UNKNOWN_FIELD",
-			"error",
-			`${where} targets "${key}", which is neither an "x-" extension nor an allowed standard field ` +
-				`(${[...ALLOWED_STANDARD_FIELDS].sort().join(", ")})`,
-		)
-		return false
-	}
-	return true
-}
-
-function compileEntry(
-	sourceKey: string,
-	entry: MetaSpecEntry | MetaSpecSchemaEntry,
-	rank: 1 | 2,
-	where: string,
-	collector: MetaSpecCollector,
-): CompiledEntry | null {
-	if (entry === false) return null
-
-	if (typeof entry === "string") {
-		if (!checkTargetKey(entry, where, collector)) return null
-		return {
-			from: null,
-			http: true,
-			keys: [entry],
-			match: null,
-			produce: (value) => (value === undefined ? undefined : { [entry]: value }),
-			profiles: null,
-			rank,
-			read: sourceKey,
-			schema: null,
-			search: "root",
-			sourceKey,
-			version: null,
-			ws: true,
-		}
-	}
-
-	const flags = targetFlags(entry.on)
-	const from = "from" in entry && entry.from ? entry.from : null
-	const base = {
-		from,
-		http: flags.http,
-		match: ("match" in entry && entry.match) || null,
-		profiles: entry.profiles ?? null,
-		rank,
-		read: (("read" in entry && entry.read) || sourceKey) as string,
-		schema: entry.schema ?? null,
-		search: ("search" in entry && entry.search) || "root",
-		sourceKey,
-		version: ("version" in entry && entry.version) || null,
-		ws: flags.ws,
-	}
-
-	if ("expand" in entry) {
-		const expand = entry.expand as (value: unknown, ctx: MetaSpecContext) => Record<string, unknown> | undefined
-		return {
-			...base,
-			keys: [],
-			produce: (value, ctx) => {
-				const out = expand(value, ctx)
-				if (out === null || out === undefined) return undefined
-				const kept: Record<string, unknown> = {}
-				for (const [k, v] of Object.entries(out)) {
-					if (v === undefined) continue
-					if (!checkTargetKey(k, `${where} (expand)`, collector)) continue
-					kept[k] = v
-				}
-				return Object.keys(kept).length > 0 ? kept : undefined
-			},
-		}
-	}
-
-	const single = entry as { key: string; map?: (value: unknown, ctx: MetaSpecContext) => unknown }
-	if (!checkTargetKey(single.key, where, collector)) return null
-	return {
-		...base,
-		keys: [single.key],
-		produce: (value, ctx) => {
-			const mapped = single.map ? single.map(value, ctx) : value
-			return mapped === undefined ? undefined : { [single.key]: mapped }
-		},
-	}
-}
-
-/** Do two entries ever write to the same operation? Only if their targets and profiles overlap. */
-function entriesOverlap(a: CompiledEntry, b: CompiledEntry): boolean {
-	if (!((a.http && b.http) || (a.ws && b.ws))) return false
-	if (a.profiles === null || b.profiles === null) return true
-	return a.profiles.some((p) => (b.profiles as readonly string[]).includes(p))
-}
-
-function detectDuplicates(entries: readonly CompiledEntry[], collector: MetaSpecCollector): void {
-	const byKey = new Map<string, CompiledEntry[]>()
-	for (const entry of entries) {
-		for (const key of entry.keys) {
-			const id = `${entry.rank} ${key}`
-			const prior = byKey.get(id) ?? []
-			const clash = prior.find((p) => p.sourceKey !== entry.sourceKey && entriesOverlap(p, entry))
-			if (clash !== undefined) {
-				collector.add(
-					"DUPLICATE_TARGET",
-					"error",
-					`"${clash.sourceKey}" and "${entry.sourceKey}" both write operation key "${key}" at the same precedence`,
-				)
-				continue
-			}
-			prior.push(entry)
-			byKey.set(id, prior)
-		}
-	}
-}
-
-export function compileMetaSpec(config: MetaSpecConfig | null, collector: MetaSpecCollector): CompiledMetaSpec {
-	const entries: CompiledEntry[] = []
-	const known = new Set<string>(BUILTIN_HIDDEN)
-
-	const overrides = config?.meta ?? {}
-	for (const builtin of builtinEntries()) {
-		known.add(builtin.sourceKey)
-		if (Object.hasOwn(overrides, builtin.sourceKey)) continue
-		entries.push(builtin)
-	}
-
-	/* app meta entries — overrides land in the built-in slot order, new keys append */
-	for (const [sourceKey, entry] of Object.entries(overrides)) {
-		known.add(sourceKey)
-		const compiled = compileEntry(sourceKey, entry, 2, `meta."${sourceKey}"`, collector)
-		if (compiled) entries.push(compiled)
-	}
-
-	let needsSchemas = false
-	for (const [sourceKey, entry] of Object.entries(config?.schema ?? {})) {
-		needsSchemas = true
-		const compiled = compileEntry(sourceKey, entry, 1, `schema."${sourceKey}"`, collector)
-		if (compiled) entries.push(compiled)
-	}
-
-	detectDuplicates(entries, collector)
-
-	/* a mounted sub-app disagreed with this one — say so, rather than let it be found by
-	   diffing the worker's document against the gateway's */
-	for (const clash of config?.conflicts ?? []) {
-		if (clash.resolution === "hidden") {
-			collector.add(
-				"SUBAPP_ENTRY_CONFLICT",
-				"warn",
-				`${clash.section}."${clash.key}": a mounted sub-app hides this key, so it is hidden here too — ` +
-					"hiding wins over a parent entry, because a leak is worse than a missing tag",
-			)
-			continue
-		}
-		collector.add(
-			"SUBAPP_ENTRY_CONFLICT",
-			"warn",
-			`${clash.section}."${clash.key}": a mounted sub-app declares a different entry; this app's entry wins ` +
-				"for this document. The sub-app's own document still uses its own entry",
-		)
-	}
-
-	return {
-		entries,
-		known,
-		needsSchemas,
-		profiles: config?.profiles ?? {},
-		strict: resolvedStrictness(config),
-	}
-}
-
-/* ---- composition ---- */
-
-/**
- * Meta keys a published artifact (the served manifest) may carry: keys with a policy entry
- * that is not `false`, plus the built-ins. Keys with no entry are unreviewed, so they stay out.
- */
-export function publishableMetaKeys(config: MetaSpecConfig | null): (key: string) => boolean {
-	const hidden = new Set(BUILTIN_HIDDEN)
-	const allowed = new Set(builtinEntries().map((e) => e.sourceKey))
-	for (const [key, entry] of Object.entries(config?.meta ?? {})) {
-		if (entry === false) {
-			hidden.add(key)
-			allowed.delete(key)
-		} else {
-			allowed.add(key)
-		}
-	}
-	return (key) => allowed.has(key) && !hidden.has(key)
-}
-
-/* ---- profile filtering ---- */
-
-export function resolveProfile(
-	spec: CompiledMetaSpec,
-	profile: string | undefined,
-	collector: MetaSpecCollector,
-): { filter: (key: string) => boolean; name: string } {
-	const name = profile ?? DEFAULT_PROFILE
-	if (name === DEFAULT_PROFILE && spec.profiles[name] === undefined) {
-		return { filter: () => true, name }
-	}
-	const declared = spec.profiles[name]
-	if (declared === undefined) {
-		collector.add(
-			"UNKNOWN_PROFILE",
-			"error",
-			`document requests profile "${name}", which is not declared in metaSpec.profiles`,
-		)
-		return { filter: () => true, name }
-	}
-	const include = declared.include ? new Set(declared.include) : null
-	const exclude = declared.exclude ? new Set(declared.exclude) : null
-	return {
-		filter: (key) => {
-			if (exclude?.has(key)) return false
-			if (include && key.startsWith("x-") && !include.has(key)) return false
-			return true
-		},
-		name,
-	}
-}
-
-/* ---- application ---- */
-
-/** Result of resolving one schema-metadata key against one schema source */
-export type SchemaMetaHit =
-	| { found: "ambiguous"; values: readonly unknown[] }
-	| { found: false }
-	| { found: true; value: unknown }
-
-export type SchemaMetaLookup = (
-	source: MetaSpecSchemaSource,
-	key: string,
-	search: MetaSpecSchemaSearch,
-) => SchemaMetaHit
-
-export type ApplyMetaSpecArgs = {
-	collector: MetaSpecCollector
-	filter: (key: string) => boolean
-	kind: "http" | "ws"
-	meta: Record<string, unknown> | null
-	method: string
-	operation: Record<string, unknown>
-	path: string
-	profile: string
-	schemaMeta?: SchemaMetaLookup
-	spec: CompiledMetaSpec
-}
-
-function validateProduced(entry: CompiledEntry, value: unknown, where: string, collector: MetaSpecCollector): boolean {
-	if (!entry.schema) return true
-	const result = entry.schema["~standard"].validate(value)
-	if (result instanceof Promise) {
-		collector.add("ASYNC_VALIDATION", "error", `${where} has an async output schema — codegen validation is sync`)
-		return false
-	}
-	if (result.issues && result.issues.length > 0) {
-		const detail = result.issues
-			.map((i) => i.message)
-			.slice(0, 3)
-			.join("; ")
-		collector.add("INVALID_VALUE", "error", `${where} produced a value rejected by its schema: ${detail}`)
-		return false
-	}
-	return true
-}
-
-/** Shallow subset check — the discriminant of a published union, e.g. `{ kind: "entity" }`. */
-function satisfiesMatch(descriptor: unknown, match: Record<string, unknown>): boolean {
-	if (descriptor === null || typeof descriptor !== "object" || Array.isArray(descriptor)) return false
-	const record = descriptor as Record<string, unknown>
-	for (const [key, expected] of Object.entries(match)) {
-		if (record[key] !== expected) return false
-	}
-	return true
-}
-
-function describeMatch(match: Record<string, unknown>): string {
-	return Object.entries(match)
-		.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
-		.join(", ")
-}
-
-/**
- * Resolve one schema entry against the route's schemas.
- *
- * Sources are walked in order. A descriptor that fails the entry's `match` does not end the
- * walk — a publisher that stamps one reserved key with a union puts different members on
- * different schemas, and an entity entry must be free to skip past the query descriptor. But
- * if no source yields a match and something *was* found under the key, that is a build error:
- * a stamped descriptor nobody claimed is a misconfiguration, not an absent fact.
- */
-function resolveSchemaEntry(
-	entry: CompiledEntry,
-	schemaMeta: SchemaMetaLookup,
-	ctx: { collector: MetaSpecCollector; method: string; path: string },
-): { source: MetaSpecSchemaSource; value: unknown } | null {
-	const { collector, method, path } = ctx
-	const where = `${method} ${path} — schema."${entry.sourceKey}"`
-	const unclaimed: { source: MetaSpecSchemaSource; value: unknown }[] = []
-
-	for (const src of entry.from ?? SCHEMA_SOURCES) {
-		const hit = schemaMeta(src, entry.read, entry.search)
-		if (hit.found === false) continue
-		if (hit.found === "ambiguous") {
-			collector.add(
-				"AMBIGUOUS_SCHEMA_KEY",
-				"error",
-				`${where} matched ${hit.values.length} different values under "${src}" (search: "deep"). ` +
-					`Stamp the key once, or narrow \`from\``,
-			)
-			return null
-		}
-
-		/* version before match: a descriptor from a newer contract may have redefined the
-		   discriminant itself, so refusing beats interpreting it */
-		if (entry.version) {
-			const field = entry.version.field ?? "v"
-			const descriptor = hit.value
-			const raw =
-				descriptor !== null && typeof descriptor === "object" && !Array.isArray(descriptor)
-					? (descriptor as Record<string, unknown>)[field]
-					: undefined
-			if (typeof raw !== "number" || !Number.isInteger(raw)) {
-				collector.add(
-					"UNSUPPORTED_VERSION",
-					"error",
-					`${where} read a descriptor from "${src}" with no integer \`${field}\` — cannot tell which contract it follows`,
-				)
-				return null
-			}
-			if (raw > entry.version.max) {
-				collector.add(
-					"UNSUPPORTED_VERSION",
-					"error",
-					`${where} read a v${raw} descriptor from "${src}" but handles up to v${entry.version.max} — ` +
-						`refusing to emit a partly-understood tag. Update the entry, or pin the publisher`,
-				)
-				return null
-			}
-		}
-
-		if (entry.match && !satisfiesMatch(hit.value, entry.match)) {
-			unclaimed.push({ source: src, value: hit.value })
-			continue
-		}
-		return { source: src, value: hit.value }
-	}
-
-	if (unclaimed.length > 0 && entry.match) {
-		const seen = unclaimed
-			.map((u) => `"${u.source}"`)
-			.sort()
-			.join(", ")
-		collector.add(
-			"DESCRIPTOR_MISMATCH",
-			"error",
-			`${where} reads "${entry.read}" expecting ${describeMatch(entry.match)}, but the descriptor found on ` +
-				`${seen} does not match. Point \`from\` at the schema carrying it, or add an entry that claims it`,
-		)
-	}
-	return null
-}
-
-export function applyMetaSpec(args: ApplyMetaSpecArgs): void {
-	const { collector, filter, kind, meta, method, operation, path, profile, schemaMeta, spec } = args
-	const metaObj = meta ?? {}
-
-	/* rank per emitted key; a key is written once, at its first contribution */
-	const ranks = new Map<string, number>()
-	const owners = new Map<string, string>()
-
-	const write = (key: string, value: unknown, rank: number, owner: string): void => {
-		if (!filter(key)) return
-		const prev = ranks.get(key)
-		if (prev !== undefined && prev > rank) return
-		if (prev === rank) {
-			const other = owners.get(key)
-			if (other !== undefined && other !== owner) {
-				collector.add(
-					"DUPLICATE_TARGET",
-					"error",
-					`${method} ${path}: "${other}" and "${owner}" both write operation key "${key}" at the same precedence`,
-				)
-				return
-			}
-		}
-		ranks.set(key, rank)
-		owners.set(key, owner)
-		operation[key] = value
-	}
-
-	for (const entry of spec.entries) {
-		if (kind === "http" ? !entry.http : !entry.ws) continue
-		if (entry.profiles && !entry.profiles.includes(profile)) continue
-
-		let value: unknown
-		let source: MetaSpecContext["source"]
-
-		if (entry.rank === 1) {
-			if (!schemaMeta) continue
-			const resolved = resolveSchemaEntry(entry, schemaMeta, { collector, method, path })
-			if (resolved === null) continue
-			value = resolved.value
-			source = resolved.source
-		} else {
-			if (!Object.hasOwn(metaObj, entry.sourceKey)) continue
-			value = metaObj[entry.sourceKey]
-			source = "meta"
-		}
-
-		const where = `${method} ${path} — ${entry.rank === 1 ? "schema" : "meta"}."${entry.sourceKey}"`
-		let produced: Record<string, unknown> | undefined
-		try {
-			produced = entry.produce(value, { meta: metaObj, method, path, profile, source })
-		} catch (err) {
-			collector.add("MAP_THREW", "error", `${where} threw: ${err instanceof Error ? err.message : String(err)}`)
-			continue
-		}
-		if (produced === undefined) continue
-
-		const validationTarget = entry.keys.length === 1 ? produced[entry.keys[0]] : produced
-		if (!validateProduced(entry, validationTarget, where, collector)) continue
-
-		for (const [key, val] of Object.entries(produced)) {
-			write(key, val, entry.rank, `${entry.rank === 1 ? "schema" : "meta"}."${entry.sourceKey}"`)
-		}
-	}
-
-	/* escape hatch — highest precedence */
-	const extensions = metaObj.extensions
-	if (extensions !== null && typeof extensions === "object" && !Array.isArray(extensions)) {
-		for (const [key, val] of Object.entries(extensions as Record<string, unknown>)) {
-			if (val === undefined) continue
-			/* extensions is typed `Record<\`x-${string}\`, unknown>` — keep runtime to the same
-			   contract. It outranks every policy entry, so letting it reach a standard field
-			   would let untyped passthrough silently override a route's own summary. */
-			if (!key.startsWith("x-")) {
-				collector.add(
-					"UNKNOWN_FIELD",
-					"error",
-					`${method} ${path} — meta.extensions may only set "x-" extensions, got "${key}"`,
-				)
-				continue
-			}
-			write(key, val, 3, "meta.extensions")
-		}
-	}
-
-	/* totality — a meta key with no entry is rot, not a shortcut */
-	if (spec.strict !== "off") {
-		for (const key of Object.keys(metaObj)) {
-			if (spec.known.has(key)) continue
-			if (collector.reportedMissing.has(key)) continue
-			collector.reportedMissing.add(key)
-			collector.add(
-				"MISSING_ENTRY",
-				spec.strict === "error" ? "error" : "warn",
-				`meta key "${key}" (first seen on ${method} ${path}) has no metaSpec entry — ` +
-					`map it to an operation key or set it to \`false\` to hide it`,
-			)
-		}
-	}
-}