@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/meta/meta-spec-apply.js

@@ -0,0 +1,83 @@
+import { claimDescriptor, validProduced, } from "./meta-spec-validate.js";
+/** The value an entry turns into operation fields, and where it came from; `null` for none. */
+function sourceOf(entry, args, where) {
+    const meta = args.meta ?? {};
+    if (entry.rank === 2)
+        return Object.hasOwn(meta, entry.sourceKey) ? { source: "meta", value: meta[entry.sourceKey] } : null;
+    return args.schemaMeta === undefined ? null : claimDescriptor(entry, args.schemaMeta, where, args.diagnostics);
+}
+/**
+ * Write the operation fields `spec` derives for one route into `operation`. A key is written at
+ * its first, highest-ranked contribution: route meta over schema metadata, `meta.extensions` over both.
+ */
+export function applyMetaSpec(args) {
+    const { diagnostics, method, operation, path, spec } = args;
+    const meta = args.meta ?? {};
+    const written = new Map();
+    const write = (key, value, rank, owner) => {
+        const prior = written.get(key);
+        if (!args.filter(key) || (prior !== undefined && prior[0] > rank))
+            return;
+        if (prior !== undefined && prior[0] === rank && prior[1] !== owner) {
+            const both = `"${prior[1]}" and "${owner}"`;
+            diagnostics.add("DUPLICATE_TARGET", "error", `${method} ${path}: ${both} both write operation key "${key}" at the same precedence`);
+            return;
+        }
+        written.set(key, [rank, owner]);
+        operation[key] = value;
+    };
+    for (const entry of spec.entries) {
+        if (!(args.kind === "http" ? entry.http : entry.ws) || entry.profiles?.includes(args.profile) === false)
+            continue;
+        const owner = `${entry.rank === 1 ? "schema" : "meta"}."${entry.sourceKey}"`;
+        const where = `${method} ${path} — ${owner}`;
+        const found = sourceOf(entry, args, where);
+        if (found === null)
+            continue;
+        let produced;
+        try {
+            produced = entry.produce(found.value, { meta, method, path, profile: args.profile, source: found.source });
+        }
+        catch (error) {
+            /* a policy error: the diagnostics carry it to the caller, whose throwIfErrors() fails the build */
+            diagnostics.add("MAP_THREW", "error", `${where} threw: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (produced === undefined)
+            continue;
+        const checked = entry.keys.length === 1 ? produced[entry.keys[0]] : produced;
+        if (!validProduced(entry.schema, checked, where, diagnostics))
+            continue;
+        for (const [key, value] of Object.entries(produced))
+            write(key, value, entry.rank, owner);
+    }
+    writeExtensions(meta.extensions, args, (key, value) => write(key, value, 3, "meta.extensions"));
+    checkTotality(meta, args);
+}
+/** `meta.extensions`: `x-` keys only, written above every entry. */
+function writeExtensions(extensions, args, write) {
+    if (extensions === null || typeof extensions !== "object" || Array.isArray(extensions))
+        return;
+    for (const [key, value] of Object.entries(extensions)) {
+        if (value === undefined)
+            continue;
+        if (key.startsWith("x-"))
+            write(key, value);
+        else {
+            const message = `${args.method} ${args.path} — meta.extensions may only set "x-" extensions, got "${key}"`;
+            args.diagnostics.add("UNKNOWN_FIELD", "error", message);
+        }
+    }
+}
+/** Under a declared policy, every meta key needs an entry: a key without one is reported once. */
+function checkTotality(meta, { diagnostics, method, path, spec }) {
+    if (spec.strict === "off")
+        return;
+    for (const key of Object.keys(meta)) {
+        if (spec.known.has(key) || diagnostics.reportedMissing.has(key))
+            continue;
+        diagnostics.reportedMissing.add(key);
+        const hint = "map it to an operation key or set it to `false` to hide it";
+        diagnostics.add("MISSING_ENTRY", spec.strict, `meta key "${key}" (first seen on ${method} ${path}) has no metaSpec entry — ${hint}`);
+    }
+}

package/dist/meta/meta-spec-merge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The metaSpec policy model, and its composition across mounted sub-apps. Kept apart from the
+ * engine, so an app holds and merges policies without loading it.
+ */
+import { GRAPH } from "../routing/app.ts";
+import type { OpenApiMeta } from "../routing/app-types.ts";
+import type { HoneyGraph } from "../routing/register.ts";
+import type { StandardSchemaLike } from "../validation/standard-schema.ts";
+/** Where a schema entry reads its descriptor. */
+export type MetaSpecSchemaSource = "input.cookies" | "input.form" | "input.headers" | "input.json" | "input.search" | "output";
+/** What a `map` or `expand` is told about the value it turns into operation fields. */
+export type MetaSpecContext = {
+    readonly meta: Readonly<Record<string, unknown>>;
+    readonly method: string;
+    readonly path: string;
+    readonly profile: string;
+    readonly source: "meta" | MetaSpecSchemaSource;
+};
+type EntryBase = {
+    /** the operations an entry applies to; default both */
+    readonly on?: "both" | "http" | "ws";
+    /** the documents an entry applies to; default every profile */
+    readonly profiles?: readonly string[];
+    /** checks the produced value at generate time; a failure is a build error */
+    readonly schema?: StandardSchemaLike;
+};
+/** An entry writing one operation key; a map answering undefined leaves it out. */
+export type MetaSpecSingle<TValue = unknown> = EntryBase & {
+    readonly key: string;
+    readonly map?: (value: TValue, ctx: MetaSpecContext) => unknown;
+};
+/** An entry fanning one value out to several operation keys; undefined leaves a key, or all, out. */
+export type MetaSpecExpand<TValue = unknown> = EntryBase & {
+    readonly expand: (value: TValue, ctx: MetaSpecContext) => Record<string, unknown> | undefined;
+};
+/** One entry: hidden (`false`), verbatim (`"x-foo"`), one key, or a fan-out. */
+export type MetaSpecEntry<TValue = unknown> = false | MetaSpecExpand<TValue> | MetaSpecSingle<TValue> | string;
+/** `"root"`: the schema, or an array's items; `"deep"`: the shallowest hit anywhere below. */
+export type MetaSpecSchemaSearch = "deep" | "root";
+/** Refuse a descriptor from a publisher contract newer than `max`. */
+export type MetaSpecVersionGuard = {
+    readonly field?: string;
+    readonly max: number;
+};
+/** An entry reading its value off a route schema's metadata rather than route meta. */
+export type MetaSpecSchemaEntry<TValue = unknown> = (MetaSpecExpand<TValue> | MetaSpecSingle<TValue>) & {
+    readonly from?: readonly MetaSpecSchemaSource[];
+    /** the discriminant this entry claims, e.g. `{ kind: "entity" }` */
+    readonly match?: Readonly<Record<string, unknown>>;
+    /** the metadata key to read; default the entry's name */
+    readonly read?: string;
+    readonly search?: MetaSpecSchemaSearch;
+    readonly version?: MetaSpecVersionGuard;
+};
+/** A per-document filter: `include` allowlists `x-` keys, `exclude` drops any key. */
+export type MetaSpecProfile = {
+    readonly exclude?: readonly string[];
+    readonly include?: readonly string[];
+};
+export type MetaSpecStrictness = "error" | "off" | "warn";
+/** A sub-app's entry that disagreed with its parent's: hidden (the sub's false won) or the parent's. */
+export type MetaSpecMergeConflict = {
+    readonly key: string;
+    readonly resolution: "hidden" | "parent";
+    readonly section: "meta" | "profiles" | "schema";
+};
+type Sections<TMeta> = {
+    readonly meta?: TMeta;
+    readonly profiles?: Readonly<Record<string, MetaSpecProfile>>;
+    readonly schema?: Readonly<Record<string, MetaSpecSchemaEntry<never>>>;
+    /** how a meta key without an entry is reported; default error */
+    readonly strict?: MetaSpecStrictness;
+};
+/** A policy as stored: untyped meta keys, and the conflicts a merge recorded. */
+export type MetaSpecConfig = Sections<Readonly<Record<string, MetaSpecEntry<never>>>> & {
+    readonly conflicts?: readonly MetaSpecMergeConflict[];
+};
+type Defined<T> = Exclude<T, undefined>;
+/** A policy for an app whose meta is `TMeta`: every key it adds needs an entry, built-ins may have one. */
+export type HoneyMetaSpec<TMeta = unknown> = [TMeta] extends [never] ? MetaSpecConfig : TMeta extends Record<string, unknown> ? Sections<{
+    readonly [K in Extract<keyof TMeta, keyof OpenApiMeta>]?: MetaSpecEntry<Defined<TMeta[K]>>;
+} & {
+    readonly [K in Exclude<keyof TMeta, keyof OpenApiMeta>]-?: MetaSpecEntry<Defined<TMeta[K]>>;
+}> : MetaSpecConfig;
+/** The strictness a declared policy runs with: `"error"` unless it says otherwise; `"off"` without one. */
+export declare function resolvedStrictness(config: MetaSpecConfig | null): MetaSpecStrictness;
+/**
+ * A mounted sub-app's policy under its parent's. The parent wins a disagreement, so a gateway
+ * keeps one answer for its document; but a sub's `false` wins over anything, because hiding is
+ * a safety claim: wrongly hidden is a visible gap, wrongly published is a leak. Strictness is
+ * the parent's resolved one, so a sub's `"off"` cannot downgrade it. Each disagreement is recorded.
+ */
+export declare function mergeMetaSpec(own: MetaSpecConfig | null, sub: MetaSpecConfig | null): MetaSpecConfig | null;
+/** A policy as an app holds it: its own declaration and each mounted sub-app's source, merged on read. */
+export type MetaSpecSource = {
+    declared: MetaSpecConfig | null;
+    readonly absorbed: MetaSpecSource[];
+};
+/** The policy `app` documents with: its own, with each mounted sub-app's merged in mount order. */
+export declare function metaSpecOf(app: {
+    readonly [GRAPH]: HoneyGraph;
+}): MetaSpecConfig | null;
+export {};

package/dist/meta/meta-spec-merge.js

@@ -0,0 +1,50 @@
+/**
+ * The metaSpec policy model, and its composition across mounted sub-apps. Kept apart from the
+ * engine, so an app holds and merges policies without loading it.
+ */
+import { GRAPH } from "../routing/app.js";
+/** The strictness a declared policy runs with: `"error"` unless it says otherwise; `"off"` without one. */
+export function resolvedStrictness(config) {
+    return config === null ? "off" : (config.strict ?? "error");
+}
+/** Each key `sub` and `own` both hold with different entries, resolved to the parent. */
+function overlaps(section, own, sub) {
+    return Object.entries(sub ?? {})
+        .filter(([key, entry]) => own?.[key] !== undefined && own[key] !== entry)
+        .map(([key]) => ({ key, resolution: "parent", section }));
+}
+/**
+ * A mounted sub-app's policy under its parent's. The parent wins a disagreement, so a gateway
+ * keeps one answer for its document; but a sub's `false` wins over anything, because hiding is
+ * a safety claim: wrongly hidden is a visible gap, wrongly published is a leak. Strictness is
+ * the parent's resolved one, so a sub's `"off"` cannot downgrade it. Each disagreement is recorded.
+ */
+export function mergeMetaSpec(own, sub) {
+    if (sub === null)
+        return own;
+    if (own === null)
+        return sub;
+    const meta = { ...sub.meta, ...own.meta };
+    const conflicts = [...(own.conflicts ?? []), ...(sub.conflicts ?? [])];
+    for (const conflict of overlaps("meta", own.meta, sub.meta)) {
+        const hides = sub.meta?.[conflict.key] === false && own.meta?.[conflict.key] !== false;
+        if (hides)
+            meta[conflict.key] = false;
+        conflicts.push(hides ? { ...conflict, resolution: "hidden" } : conflict);
+    }
+    conflicts.push(...overlaps("schema", own.schema, sub.schema), ...overlaps("profiles", own.profiles, sub.profiles));
+    return {
+        conflicts,
+        meta,
+        profiles: { ...sub.profiles, ...own.profiles },
+        schema: { ...sub.schema, ...own.schema },
+        strict: resolvedStrictness(own),
+    };
+}
+function resolve(source) {
+    return source.absorbed.reduce((merged, sub) => mergeMetaSpec(merged, resolve(sub)), source.declared);
+}
+/** The policy `app` documents with: its own, with each mounted sub-app's merged in mount order. */
+export function metaSpecOf(app) {
+    return resolve(app[GRAPH].settings.metaSpec);
+}

package/dist/meta/meta-spec-validate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The metaSpec checks: the diagnostics a policy run collects (never printed: the caller throws
+ * the errors and reports the warnings), the gate on what a policy may write, the check of each
+ * produced value, and reading a descriptor off a route's JSON Schema.
+ */
+import type { JsonSchema } from "../schema/to-json-schema.ts";
+import type { StandardSchemaLike } from "../validation/standard-schema.ts";
+import type { MetaSpecSchemaSearch, MetaSpecSchemaSource, MetaSpecVersionGuard } from "./meta-spec.ts";
+export type MetaSpecDiagnosticCode = "AMBIGUOUS_SCHEMA_KEY" | "ASYNC_VALIDATION" | "DESCRIPTOR_MISMATCH" | "DUPLICATE_OPERATION_ID" | "DUPLICATE_TARGET" | "INVALID_SELECTOR" | "INVALID_SERVER" | "INVALID_TAG" | "INVALID_VALUE" | "INVALID_WEBHOOK" | "MAP_THREW" | "MISSING_ENTRY" | "RESERVED_FIELD" | "SCHEMA_DEGRADED" | "SCHEMA_FAILED" | "SUBAPP_ENTRY_CONFLICT" | "UNKNOWN_FIELD" | "UNKNOWN_PROFILE" | "UNKNOWN_SECURITY_SCHEME" | "UNSUPPORTED_VERSION" | "UNUSED_TAG" | "WS_SHADOWED";
+export type MetaSpecDiagnostic = {
+    readonly code: MetaSpecDiagnosticCode;
+    readonly level: "error" | "warn";
+    readonly message: string;
+};
+/** What one policy run found: each code and message once, in order. */
+export declare class MetaSpecDiagnostics {
+    #private;
+    readonly list: MetaSpecDiagnostic[];
+    /** meta keys already reported as unmapped: once, not once per route */
+    readonly reportedMissing: Set<string>;
+    add(code: MetaSpecDiagnosticCode, level: "error" | "warn", message: string): void;
+    /** Throws one error naming every policy error; with none, the warnings for the caller to report. */
+    throwIfErrors(): readonly MetaSpecDiagnostic[];
+}
+/** Whether a policy may write operation key `key`: an `x-` extension or an allowed standard field. */
+export declare function checkTargetKey(key: string, where: string, diagnostics: MetaSpecDiagnostics): boolean;
+/** Whether `value` passes the entry's `schema`; validation at generate time is synchronous. */
+export declare function validProduced(schema: StandardSchemaLike | null, value: unknown, where: string, diagnostics: MetaSpecDiagnostics): boolean;
+export type SchemaMetaHit = {
+    readonly found: "ambiguous";
+    readonly values: readonly unknown[];
+} | {
+    readonly found: false;
+} | {
+    readonly found: true;
+    readonly value: unknown;
+};
+/** The value of metadata key `key` on a route's schema of `source`. */
+export type SchemaMetaLookup = (source: MetaSpecSchemaSource, key: string, search: MetaSpecSchemaSearch) => SchemaMetaHit;
+/**
+ * A lookup over a route's schemas by source. A root search reads the schema, and for an array
+ * its items one level down; a deep search walks properties, items and members to the shallowest hit.
+ */
+export declare function schemaMetaLookup(roots: Readonly<Partial<Record<MetaSpecSchemaSource, JsonSchema>>>): SchemaMetaLookup;
+/** What a schema entry reads, and which descriptor it claims. */
+export type SchemaRead = {
+    readonly from: readonly MetaSpecSchemaSource[];
+    readonly match: Readonly<Record<string, unknown>> | null;
+    readonly read: string;
+    readonly search: MetaSpecSchemaSearch;
+    readonly version: MetaSpecVersionGuard | null;
+};
+/**
+ * The descriptor a schema entry claims, searching its sources in order. One that fails `match`
+ * is skipped, since a union puts its members on different schemas; but a descriptor nothing
+ * claims is a build error, never a silently missing tag.
+ */
+export declare function claimDescriptor(entry: SchemaRead, lookup: SchemaMetaLookup, where: string, diagnostics: MetaSpecDiagnostics): {
+    readonly source: MetaSpecSchemaSource;
+    readonly value: unknown;
+} | null;

package/dist/meta/meta-spec-validate.js

@@ -0,0 +1,166 @@
+/** How many errors an aggregate error lists before it only counts. */
+const LISTED = 20;
+/** What one policy run found: each code and message once, in order. */
+export class MetaSpecDiagnostics {
+    list = [];
+    /** meta keys already reported as unmapped: once, not once per route */
+    reportedMissing = new Set();
+    #seen = new Set();
+    add(code, level, message) {
+        const key = `${code}\u0000${message}`;
+        if (this.#seen.has(key))
+            return;
+        this.#seen.add(key);
+        this.list.push({ code, level, message });
+    }
+    /** Throws one error naming every policy error; with none, the warnings for the caller to report. */
+    throwIfErrors() {
+        const errors = this.list.filter(({ level }) => level === "error");
+        if (errors.length === 0)
+            return this.list;
+        const shown = errors.slice(0, LISTED).map(({ code, message }) => `  - ${code}: ${message}`);
+        const more = errors.length > LISTED ? `\n  … and ${errors.length - LISTED} more` : "";
+        throw new Error(`[honey:metaSpec] ${errors.length} policy error(s):\n${shown.join("\n")}${more}`);
+    }
+}
+/** Standard operation fields a policy may write. */
+const STANDARD = [
+    "deprecated",
+    "description",
+    "externalDocs",
+    "operationId",
+    "security",
+    "servers",
+    "summary",
+    "tags",
+];
+/** Fields the route's schemas and error keys own: a policy writing them would contradict the route. */
+const RESERVED = ["callbacks", "parameters", "requestBody", "responses"];
+/** Whether a policy may write operation key `key`: an `x-` extension or an allowed standard field. */
+export function checkTargetKey(key, where, diagnostics) {
+    if (key.startsWith("x-") || STANDARD.includes(key))
+        return true;
+    if (RESERVED.includes(key)) {
+        diagnostics.add("RESERVED_FIELD", "error", `${where} targets reserved operation field "${key}"`);
+        return false;
+    }
+    diagnostics.add("UNKNOWN_FIELD", "error", `${where} targets "${key}", which is neither an "x-" extension nor an allowed standard field (${STANDARD.join(", ")})`);
+    return false;
+}
+/** Whether `value` passes the entry's `schema`; validation at generate time is synchronous. */
+export function validProduced(schema, value, where, diagnostics) {
+    if (schema === null)
+        return true;
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise) {
+        diagnostics.add("ASYNC_VALIDATION", "error", `${where} has an async output schema — generate-time validation is sync`);
+        return false;
+    }
+    if (result.issues === undefined || result.issues.length === 0)
+        return true;
+    const detail = result.issues
+        .slice(0, 3)
+        .map(({ message }) => message)
+        .join("; ");
+    diagnostics.add("INVALID_VALUE", "error", `${where} produced a value rejected by its schema: ${detail}`);
+    return false;
+}
+const NOT_FOUND = { found: false };
+/** How many levels a deep search descends. */
+const DEEP_LEVELS = 6;
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A schema's own value of `key`, when it has one. */
+function own(schema, key) {
+    return isRecord(schema) && Object.hasOwn(schema, key) && schema[key] !== undefined
+        ? { found: true, value: schema[key] }
+        : NOT_FOUND;
+}
+/** The schemas directly under `schema`: its properties, items and composition members. */
+function children(schema) {
+    const properties = isRecord(schema.properties) ? Object.values(schema.properties) : [];
+    const members = ["allOf", "anyOf", "oneOf", "prefixItems"].flatMap((key) => {
+        const list = schema[key];
+        return Array.isArray(list) ? list : [];
+    });
+    return [...properties, schema.items, ...members].filter(isRecord);
+}
+/** The shallowest level holding `key`: one value found, or two different ones refused. */
+function deepSearch(root, key) {
+    let level = [root];
+    for (let depth = 0; depth <= DEEP_LEVELS && level.length > 0; depth++) {
+        const found = new Map();
+        for (const schema of level) {
+            const hit = own(schema, key);
+            if (hit.found === true)
+                found.set(JSON.stringify(hit.value), hit.value);
+        }
+        if (found.size === 1)
+            return { found: true, value: [...found.values()][0] };
+        if (found.size > 1)
+            return { found: "ambiguous", values: [...found.values()] };
+        level = level.flatMap(children);
+    }
+    return NOT_FOUND;
+}
+/**
+ * A lookup over a route's schemas by source. A root search reads the schema, and for an array
+ * its items one level down; a deep search walks properties, items and members to the shallowest hit.
+ */
+export function schemaMetaLookup(roots) {
+    return (source, key, search) => {
+        const root = roots[source];
+        if (root === undefined)
+            return NOT_FOUND;
+        if (search === "deep")
+            return deepSearch(root, key);
+        const hit = own(root, key);
+        return hit.found === false && root.type === "array" ? own(root.items, key) : hit;
+    };
+}
+/** Why a descriptor's version is refused, or `null` when this entry handles it. */
+function refusedVersion(descriptor, guard) {
+    const field = guard.field ?? "v";
+    const version = isRecord(descriptor) ? descriptor[field] : undefined;
+    if (typeof version !== "number" || !Number.isInteger(version)) {
+        return `with no integer \`${field}\` — cannot tell which contract it follows`;
+    }
+    if (version <= guard.max)
+        return null;
+    return `v${version} but handles up to v${guard.max} — refusing to emit a partly-understood tag`;
+}
+/** Whether `descriptor` holds every key of `match` with its value: the discriminant of a union. */
+function satisfiesMatch(descriptor, match) {
+    return isRecord(descriptor) && Object.entries(match).every(([key, value]) => descriptor[key] === value);
+}
+/**
+ * The descriptor a schema entry claims, searching its sources in order. One that fails `match`
+ * is skipped, since a union puts its members on different schemas; but a descriptor nothing
+ * claims is a build error, never a silently missing tag.
+ */
+export function claimDescriptor(entry, lookup, where, diagnostics) {
+    const unclaimed = [];
+    for (const source of entry.from) {
+        const hit = lookup(source, entry.read, entry.search);
+        if (hit.found === false)
+            continue;
+        if (hit.found === "ambiguous") {
+            const count = hit.values.length;
+            diagnostics.add("AMBIGUOUS_SCHEMA_KEY", "error", `${where} matched ${count} different values under "${source}"`);
+            return null;
+        }
+        /* version before match: a newer contract may have redefined the discriminant itself */
+        const refused = entry.version === null ? null : refusedVersion(hit.value, entry.version);
+        if (refused !== null) {
+            diagnostics.add("UNSUPPORTED_VERSION", "error", `${where} read a descriptor from "${source}" ${refused}`);
+            return null;
+        }
+        if (entry.match === null || satisfiesMatch(hit.value, entry.match))
+            return { source, value: hit.value };
+        unclaimed.push(source);
+    }
+    if (unclaimed.length > 0) {
+        const seen = unclaimed.map((source) => `"${source}"`).join(", ");
+        diagnostics.add("DESCRIPTOR_MISMATCH", "error", `${where} reads "${entry.read}" expecting ${JSON.stringify(entry.match)}, but the descriptor on ${seen} does not match`);
+    }
+    return null;
+}

package/dist/meta/meta-spec.d.ts

@@ -0,0 +1,49 @@
+/**
+ * metaSpec: the generate-time policy that turns route meta and route schemas into OpenAPI
+ * operation fields. Never consulted at request time; what it finds goes to the diagnostics,
+ * which the caller throws or reports.
+ */
+import { type MetaSpecConfig, type MetaSpecContext, type MetaSpecProfile, type MetaSpecStrictness } from "./meta-spec-merge.ts";
+import type { StandardSchemaLike } from "../validation/standard-schema.ts";
+import { type MetaSpecDiagnostics, type SchemaRead } from "./meta-spec-validate.ts";
+export type { HoneyMetaSpec, MetaSpecConfig, MetaSpecContext, MetaSpecEntry, MetaSpecSchemaSearch, MetaSpecSchemaSource, MetaSpecStrictness, MetaSpecVersionGuard, } from "./meta-spec-merge.ts";
+export declare const DEFAULT_PROFILE = "default";
+/**
+ * Security shorthand → OpenAPI requirements: a name, alternative names, groups of names, or
+ * requirement objects; `[]` is explicitly public. Anything else throws: a guess would document
+ * a protected route as public.
+ */
+export declare function normalizeSecurity(raw: unknown): Record<string, string[]>[];
+/** The scheme names a security list refers to, once each. */
+export declare function securitySchemeNames(security: unknown): string[];
+export type Produce = (value: unknown, ctx: MetaSpecContext) => Record<string, unknown> | undefined;
+export type CompiledEntry = SchemaRead & {
+    readonly http: boolean;
+    /** the keys it declares, for duplicate detection; none for an expand */
+    readonly keys: readonly string[];
+    readonly produce: Produce;
+    readonly profiles: readonly string[] | null;
+    /** 1: read off a schema; 2: route meta, built-ins included; 3 is meta.extensions */
+    readonly rank: 1 | 2;
+    readonly schema: StandardSchemaLike | null;
+    readonly sourceKey: string;
+    readonly ws: boolean;
+};
+export type CompiledMetaSpec = {
+    readonly entries: readonly CompiledEntry[];
+    /** meta keys with an entry or hidden by design: what totality checks against */
+    readonly known: ReadonlySet<string>;
+    /** whether any entry reads schemas, so a document builds the lookup only when needed */
+    readonly needsSchemas: boolean;
+    readonly profiles: Readonly<Record<string, MetaSpecProfile>>;
+    readonly strict: MetaSpecStrictness;
+};
+/** `config` ready to apply: built-ins (an app entry takes its slot), app entries, then schema entries. */
+export declare function compileMetaSpec(config: MetaSpecConfig | null, diagnostics: MetaSpecDiagnostics): CompiledMetaSpec;
+/** The meta keys a published manifest may carry: built-ins and keys with an entry, never a hidden one. */
+export declare function publishableMetaKeys(config: MetaSpecConfig | null): (key: string) => boolean;
+/** The filter of the document's profile: `exclude` drops keys, `include` allowlists `x-` keys. */
+export declare function resolveProfile(spec: CompiledMetaSpec, profile: string | undefined, diagnostics: MetaSpecDiagnostics): {
+    readonly filter: (key: string) => boolean;
+    readonly name: string;
+};