@telorun/cel 0.0.0-stage → 0.108.0

package/dist/environment.js

@@ -0,0 +1,474 @@
+/**
+ * An environment: what names, functions and types an expression is read against.
+ *
+ * **Everything is registered the same way, including the standard library.** There is
+ * no privileged door: a host can replace `duration(string)` with its own, or remove a
+ * standard function so a call to it is refused, because the library came in through the
+ * same `registerFunction` a host uses. An engine with a built-in library behind a
+ * private registration is an engine whose library cannot be changed — which is the
+ * concrete thing this package exists to fix.
+ *
+ * `clone()` inherits everything and then diverges: registering or removing on the clone
+ * leaves the parent as it was. That is what lets one base environment be built once and
+ * specialised per site.
+ *
+ * **Two seams, and only two, let a host's vocabulary in**: `registerType`, for a named
+ * type over a base with its own operators and members, and `resolveSchemaType`, asked at
+ * every node of a JSON Schema before the structural rules. Nothing in this package knows
+ * any host's type names.
+ */
+import { BoundedCache } from "./bounded-cache.js";
+import { parseExpression, resolvedUnder } from "./cel-expression.js";
+import { compileExpression } from "./cel-program.js";
+import { emitModule, emitterRuntime, storedEmittedModule } from "./emitted-module.js";
+import { environmentDigest } from "./environment-digest.js";
+import { CEL_VALUE_KEYS } from "./cel-value.js";
+import { DYN, formatType } from "./cel-type.js";
+import { CelEngineError } from "./check-diagnostic.js";
+import { checkExpression } from "./checker.js";
+import { FunctionRegistry } from "./function-registry.js";
+import { fieldMapType, schemaType } from "./json-schema-type.js";
+import { normalizeNamespaces } from "./namespace-resolution.js";
+import { buildRegisteredType, CelTypeRegistrationError, nominalOperators, nominalSignatures, } from "./nominal-type.js";
+import { formatSignature, parseSignature } from "./signature.js";
+import { registerStandardLibrary, standardConstants } from "./standard-library.js";
+import { standardConstantValues } from "./runtime-library.js";
+import { parseTypeExpression } from "./type-expression.js";
+/** How many compiled expressions an environment keeps when nothing says otherwise. */
+export const DEFAULT_COMPILED_CACHE_CAPACITY = 256;
+export class CelEnvironment {
+    registry;
+    variables;
+    types;
+    namespaceFunctions;
+    /** Namespaces that declare only part of what they reach; see {@link NamespaceOptions.open}. */
+    openNamespaces;
+    constants;
+    /** Bounded: a source text is a key an author's input decides. */
+    compiled;
+    options;
+    constructor(options = {}, inherited) {
+        this.options = {
+            unlistedVariablesAreDyn: false,
+            homogeneousAggregateLiterals: false,
+            enableOptionalTypes: false,
+            ...(inherited ? inherited.options : {}),
+            ...options,
+        };
+        this.registry = new FunctionRegistry(inherited?.registry);
+        this.variables = new Map(inherited?.variables);
+        this.types = new Map(inherited?.types);
+        this.namespaceFunctions = new Map();
+        for (const [namespace, functions] of inherited?.namespaceFunctions ?? []) {
+            this.namespaceFunctions.set(namespace, new Map(functions));
+        }
+        this.openNamespaces = new Set(inherited?.openNamespaces);
+        this.constants = new Map(inherited?.constants);
+        this.compiled = new BoundedCache(this.options.compiledCacheCapacity ?? DEFAULT_COMPILED_CACHE_CAPACITY);
+        if (inherited)
+            return;
+        if (this.options.standardLibrary ?? true) {
+            for (const [name, value] of standardConstantValues(this.options.enableOptionalTypes)) {
+                this.constants.set(name, value);
+            }
+            registerStandardLibrary(this.registry, {
+                optionalTypes: this.options.enableOptionalTypes,
+                resolveNominal: this.nominalResolver,
+            });
+            for (const constant of standardConstants(this.options.enableOptionalTypes)) {
+                this.variables.set(constant.name, {
+                    type: constant.type,
+                    constant: true,
+                    ...(constant.description === undefined ? {} : { description: constant.description }),
+                });
+            }
+        }
+    }
+    /** A new environment inheriting everything, which may then diverge. */
+    clone(options = {}) {
+        return new CelEnvironment(options, this);
+    }
+    // --- registration -------------------------------------------------------
+    /**
+     * Registers a function, **replacing** any registration answering the same call.
+     *
+     * Every registration forgets what this environment compiled: a program holds the
+     * overloads its call sites resolved to, so serving a cached one after the library
+     * changed would run the function that was replaced — the precise failure the
+     * replaceable library exists to avoid.
+     */
+    registerFunction(signature, metadata = {}) {
+        this.registry.register(this.signatureOf(signature), metadata);
+        this.compiled.clear();
+        return this;
+    }
+    /** Removes the one registration answering that call. Answers whether it was there. */
+    removeFunction(signature) {
+        const removed = this.registry.remove(this.signatureOf(signature));
+        this.compiled.clear();
+        return removed;
+    }
+    /** Removes every registration of a name, so a call to it is unknown. */
+    removeFunctionsNamed(name) {
+        const removed = this.registry.removeName(name);
+        this.compiled.clear();
+        return removed;
+    }
+    /** Registers an operator over the types given, replacing one over the same types. */
+    registerOperator(operator, parameters, returns, metadata = {}) {
+        this.registry.register({
+            name: operator,
+            form: "global",
+            parameters: parameters.map((text) => this.readType(text)),
+            returns: this.readType(returns),
+        }, metadata);
+        this.compiled.clear();
+        return this;
+    }
+    registerVariable(name, declaration, metadata = {}) {
+        this.variables.set(name, {
+            ...this.typeOf(declaration),
+            constant: false,
+            ...(metadata.description === undefined ? {} : { description: metadata.description }),
+        });
+        // A declared name changes which NAME a dotted chain reads: `splitDeclaredChain` is
+        // decided at compile time from the declarations, so a program compiled before this
+        // call resolved the chain against the activation instead. Serving it afterwards is
+        // the check/run divergence that split exists to prevent, arriving through the cache.
+        this.compiled.clear();
+        return this;
+    }
+    /** A name whose value never changes; it reads exactly as a variable does. */
+    registerConstant(name, declaration, metadata = {}) {
+        this.variables.set(name, {
+            ...this.typeOf(declaration),
+            constant: true,
+            ...(metadata.description === undefined ? {} : { description: metadata.description }),
+        });
+        this.compiled.clear();
+        return this;
+    }
+    hasVariable(name) {
+        return this.variables.has(name);
+    }
+    /**
+     * Every schema-typed registration whose schema this engine could not judge whole, with
+     * each node by JSON Pointer. Empty is every node judged, which is the normal answer.
+     */
+    schemaReports() {
+        const reports = [];
+        for (const [name, held] of [...this.variables.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
+            const unjudged = held.unjudged ?? [];
+            const recursive = held.recursive ?? [];
+            if (unjudged.length === 0 && recursive.length === 0)
+                continue;
+            reports.push({ name, unjudged, recursive });
+        }
+        return reports;
+    }
+    /** Registers a named type, with every operator, conversion and member it declares. */
+    registerType(definition) {
+        // A value of a named type carries its name under the engine's own value key, so a
+        // name the engine already uses there would make two types one value.
+        if (CEL_VALUE_KEYS.includes(definition.name)) {
+            throw new CelTypeRegistrationError(`${JSON.stringify(definition.name)} is the type key of a value this engine builds`);
+        }
+        const registered = buildRegisteredType(definition, this.nominalResolver);
+        this.types.set(definition.name, registered);
+        const resolver = (name, args) => name === "Self" ? { ...registered.self, args: args.length > 0 ? args : registered.self.args } : this.nominalResolver(name, args);
+        for (const signature of nominalSignatures(definition)) {
+            this.registry.register(parseSignature(signature, resolver), {
+                deterministic: true,
+                origin: `type:${definition.name}`,
+            });
+        }
+        for (const operator of nominalOperators(definition)) {
+            this.registry.register({
+                name: operator.operator,
+                form: "global",
+                parameters: operator.parameters.map((text) => parseTypeExpression(text, resolver)),
+                returns: parseTypeExpression(operator.returns, resolver),
+            }, { deterministic: true, origin: `type:${definition.name}` });
+        }
+        this.compiled.clear();
+        return this;
+    }
+    /**
+     * Registers a namespace and the functions it declares. A namespace is a name that
+     * denotes a module rather than a value, which is what turns `Alias.fn(x)` into a
+     * qualified call rather than a method on something.
+     */
+    registerNamespace(name, functions = [], options = {}) {
+        normalizeNamespaces([name]);
+        const declared = new Map();
+        for (const declaration of functions) {
+            const entry = typeof declaration === "string" ? { signature: declaration } : declaration;
+            const flags = {
+                ...(entry.deterministic === undefined ? {} : { deterministic: entry.deterministic }),
+                ...(entry.hostBacked === undefined ? {} : { hostBacked: entry.hostBacked }),
+                ...(entry.throws === undefined ? {} : { throws: entry.throws }),
+            };
+            // A name this environment registers no type under is RECORDED and read as `dyn`,
+            // never thrown: a namespace declaration is a host's own data — a module function's
+            // declared result out of a manifest — so a typo there would otherwise be a crash
+            // with no line, and the consumer that knows where it was written is the one that
+            // can anchor the diagnostic. The checker reports it at each call.
+            const unregistered = [];
+            const resolver = (named, args) => {
+                const resolved = this.nominalResolver(named, args);
+                if (resolved)
+                    return resolved;
+                if (!unregistered.includes(named))
+                    unregistered.push(named);
+                return DYN;
+            };
+            const recorded = () => (unregistered.length > 0 ? { unregisteredTypes: [...unregistered] } : {});
+            if (entry.signature !== undefined) {
+                const signature = parseSignature(entry.signature, resolver);
+                if (signature.form !== "global") {
+                    throw new CelTypeRegistrationError(`a namespaced function is declared without a receiver: ${JSON.stringify(entry.signature)}`);
+                }
+                declared.set(signature.name, {
+                    name: signature.name,
+                    returns: signature.returns,
+                    parameters: signature.parameters,
+                    signature: formatSignature(signature),
+                    ...recorded(),
+                    ...flags,
+                });
+                continue;
+            }
+            declared.set(entry.name, {
+                name: entry.name,
+                returns: typeof entry.returns === "string" ? parseTypeExpression(entry.returns, resolver) : entry.returns,
+                ...recorded(),
+                ...flags,
+            });
+        }
+        this.namespaceFunctions.set(name, declared);
+        if (options.open === true)
+            this.openNamespaces.add(name);
+        else
+            this.openNamespaces.delete(name);
+        this.compiled.clear();
+        return this;
+    }
+    /** Every namespace registered, in canonical order. */
+    namespaces() {
+        return [...this.namespaceFunctions.keys()].sort();
+    }
+    // --- reading ------------------------------------------------------------
+    /** Reads an expression against this environment's namespaces. */
+    parse(source) {
+        return parseExpression(source, {
+            namespaces: this.namespaces(),
+            optionalSyntax: this.options.enableOptionalTypes,
+            ...(this.options.limits ? { limits: this.options.limits } : {}),
+        });
+    }
+    /**
+     * Checks an expression. A tree resolved under a different namespace set is **refused**
+     * rather than checked: its qualified calls are not the ones this environment would
+     * have found, so every answer about it would be about a different expression.
+     */
+    check(source) {
+        const expression = typeof source === "string" ? this.parse(source) : source;
+        if (typeof source !== "string" && !resolvedUnder(expression, this.namespaces())) {
+            throw new CelEngineError("namespaces_mismatch", `the expression was resolved under [${expression.namespaces.join(", ")}] and this environment has [${this.namespaces().join(", ")}]`);
+        }
+        return checkExpression(expression, {
+            registry: this.registry,
+            variable: (name) => this.variables.get(name)?.type,
+            declaredVariableNames: () => [...this.variables.keys()],
+            namespaceFunction: (namespace, name) => this.namespaceFunctions.get(namespace)?.get(name),
+            namespaceIsOpen: (namespace) => this.openNamespaces.has(namespace),
+            options: {
+                unlistedVariablesAreDyn: this.options.unlistedVariablesAreDyn,
+                homogeneousAggregateLiterals: this.options.homogeneousAggregateLiterals,
+                enableOptionalTypes: this.options.enableOptionalTypes,
+            },
+        });
+    }
+    /**
+     * Compiles an expression into a program. Nothing is type-checked here — the checker
+     * decides every verdict, and a consumer that wants one asks for it — so compiling
+     * refuses only what cannot be compiled at all: a source that did not read whole.
+     *
+     * A compile from text is memoized in a bounded cache; a tree handed over directly is
+     * compiled each time, because a tree has no identity to key on.
+     */
+    compile(source) {
+        if (typeof source !== "string")
+            return this.compileExpressionNow(source);
+        const held = this.compiled.get(source);
+        if (held)
+            return held;
+        const program = this.compileExpressionNow(this.parse(source));
+        this.compiled.set(source, program);
+        return program;
+    }
+    /** Compiles and runs an expression against an activation. */
+    evaluate(source, activation, options) {
+        return this.compile(source).evaluate(activation, options);
+    }
+    // --- the emitter ---------------------------------------------------------
+    /**
+     * The JavaScript module for a set of expressions, emitted now: its text, its key and its
+     * integrity header. The same expressions in the same order against the same environment
+     * emit byte-identically, so a host may compare two emissions instead of trusting one.
+     *
+     * The host stores and loads the text; this package touches no filesystem and exports no
+     * loader. `emitterRuntime()` is what the loaded module's factory takes, and
+     * `programsFromEmittedModule` verifies its header before anything runs.
+     */
+    emit(sources) {
+        return emitModule(this.target(), this.digest(), this.expressionsOf(sources));
+    }
+    /**
+     * The module for a set of expressions, read from the store where it holds a copy whose
+     * header matches and emitted and written where it does not — so a corrupted, stale or
+     * foreign stored copy causes a recompile rather than a run.
+     */
+    emittedModule(sources, store) {
+        // The trees are handed over as a thunk: a hit reads a header and a digest, and parsing
+        // every expression to find out whether it needed to is work with no answer attached.
+        return storedEmittedModule(this.target(), this.digest(), sources, () => this.expressionsOf(sources), store);
+    }
+    /** The runtime support library an emitted module's factory is handed. */
+    emitterRuntime() {
+        return emitterRuntime(this.target());
+    }
+    /**
+     * This environment's digest: the order-independent hash of its resolved listing, which
+     * the key and the header are both over. A host that caches by key never needs it; a host
+     * explaining a recompile does.
+     */
+    digest() {
+        return environmentDigest(this);
+    }
+    expressionsOf(sources) {
+        return sources.map((source) => ({ source, root: this.readyExpression(this.parse(source)).root }));
+    }
+    /** What the backends need of this environment, built one way for both of them. */
+    target() {
+        return {
+            registry: this.registry,
+            constants: this.constants,
+            nominalArity: (name) => this.types.get(name)?.parameters.length,
+            // The same declarations the checker splits a dotted chain on.
+            declares: (name) => this.variables.has(name),
+        };
+    }
+    /**
+     * An expression a backend may compile: read whole, and resolved under this
+     * environment's own namespaces. Nothing is type-checked — the checker decides every
+     * verdict and a consumer that wants one asks for it.
+     */
+    readyExpression(expression) {
+        if (expression.diagnostics.length > 0) {
+            throw new CelEngineError("unreadable_expression", `${JSON.stringify(expression.source)} could not be read: ${expression.diagnostics[0].message}`);
+        }
+        if (!resolvedUnder(expression, this.namespaces())) {
+            throw new CelEngineError("namespaces_mismatch", `the expression was resolved under [${expression.namespaces.join(", ")}] and this environment has [${this.namespaces().join(", ")}]`);
+        }
+        return expression;
+    }
+    compileExpressionNow(expression) {
+        return compileExpression(this.readyExpression(expression), this.target());
+    }
+    /**
+     * Whether a value of this type can be converted to text by the environment's own
+     * `string()`. A consumer that renders a value into text asks this before it tries;
+     * `dyn` passes, because only the runtime knows what it holds.
+     */
+    convertsToString(type) {
+        if (type.kind === "dyn")
+            return true;
+        return "resolved" in this.registry.resolve("string", "global", [type]);
+    }
+    /** Every registration, for a listing a host prints or compares. */
+    definitions() {
+        return {
+            variables: [...this.variables.entries()]
+                .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+                .map(([name, held]) => ({
+                name,
+                type: held.type,
+                typeName: formatType(held.type, true),
+                constant: held.constant,
+                ...(held.description === undefined ? {} : { description: held.description }),
+            })),
+            functions: this.registry.list().map((entry) => ({
+                name: entry.signature.name,
+                signature: formatSignature(entry.signature),
+                receiverType: entry.signature.receiver ? formatType(entry.signature.receiver) : null,
+                parameters: entry.signature.parameters.map((type) => formatType(type)),
+                returns: formatType(entry.signature.returns),
+                deterministic: entry.metadata.deterministic ?? true,
+                hostBacked: entry.metadata.hostBacked ?? false,
+                ...(entry.metadata.throws === undefined ? {} : { throws: entry.metadata.throws }),
+                ...(entry.metadata.description === undefined ? {} : { description: entry.metadata.description }),
+                ...(entry.metadata.origin === undefined ? {} : { origin: entry.metadata.origin }),
+            })),
+            types: [...this.types.values()].map((registered) => ({
+                name: registered.definition.name,
+                base: formatType(registered.base),
+                parameters: registered.parameters,
+                ...(registered.definition.description === undefined
+                    ? {}
+                    : { description: registered.definition.description }),
+            })),
+            namespaces: this.namespaces().map((name) => ({
+                name,
+                open: this.openNamespaces.has(name),
+                // A declaration whose parameter list is withheld has no signature text, so it is
+                // listed by what it DOES declare — its name and its result. Printing an invented
+                // empty parameter list would read as a function of no arguments.
+                functions: [...this.namespaceFunctions.get(name).values()].map((held) => held.signature ?? `${held.name}(…): ${formatType(held.returns)}`),
+            })),
+        };
+    }
+    // --- types --------------------------------------------------------------
+    nominalResolver = (name, args) => {
+        const registered = this.types.get(name);
+        if (!registered)
+            return undefined;
+        if (args.length === 0)
+            return registered.self;
+        if (args.length !== registered.parameters.length) {
+            throw new CelTypeRegistrationError(`${name} takes ${registered.parameters.length} type argument${registered.parameters.length === 1 ? "" : "s"}`);
+        }
+        return { ...registered.self, args };
+    };
+    readType(text) {
+        return parseTypeExpression(text, this.nominalResolver);
+    }
+    signatureOf(signature) {
+        return typeof signature === "string" ? parseSignature(signature, this.nominalResolver) : signature;
+    }
+    /** The type a declaration names: a type expression, a field map, or a schema. */
+    typeOf(declaration) {
+        if (typeof declaration === "string")
+            return { type: this.readType(declaration) };
+        if ("kind" in declaration)
+            return { type: declaration };
+        if ("fields" in declaration) {
+            return { type: fieldMapType(declaration.fields, (text) => this.readType(text)) };
+        }
+        if ("schema" in declaration) {
+            const converted = schemaType({
+                node: declaration.schema,
+                ...(declaration.document === undefined ? {} : { root: declaration.document }),
+            }, {
+                ...(this.options.resolveSchemaType ? { resolveSchemaType: this.options.resolveSchemaType } : {}),
+                lookupNamedType: (name, args) => this.nominalResolver(name, args.map((text) => this.readType(text))),
+            });
+            return {
+                type: converted.type,
+                ...(converted.unjudged.length === 0 ? {} : { unjudged: converted.unjudged }),
+                ...(converted.recursive.length === 0 ? {} : { recursive: converted.recursive }),
+            };
+        }
+        throw new CelTypeRegistrationError("a declaration is a type expression, a field map or a schema");
+    }
+}

package/dist/function-catalog.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Loading the function catalog into an environment.
+ *
+ * The catalog is the **dialect**: the functions a manifest may call beside CEL's own
+ * library. Like the standard library it is **data** (`signatures/function-catalog.json`)
+ * read through the same registration surface a host uses — here literally the public one,
+ * `CelEnvironment.registerFunction`, with no privileged door of any kind. A host may
+ * register the catalog, leave it out, replace one of its signatures or remove a name, and
+ * nothing in the engine behaves differently for it.
+ *
+ * **One surface, read by everything that lists the catalog.** `functionCatalog()` answers
+ * each function with its display signature, its category, its summary and its two flags,
+ * which is exactly what a `functions` listing prints; a consumer never reconstructs that
+ * from registrations.
+ *
+ * What a function DOES is beside it, per runtime — `catalog-runtime.ts`, keyed by the same
+ * dispatch key the registry resolves on. A declared signature with no behaviour there is
+ * refused at registration rather than at evaluation, which is the failure class the two
+ * artifacts exist to remove.
+ */
+import type { CelCatalogHandlers } from "./catalog-runtime.js";
+import type { CelEnvironment } from "./environment.js";
+export declare const FUNCTION_CATALOG_GENERATION: number;
+/** The categories the catalog groups its functions under, for a grouped listing. */
+export declare function catalogCategories(): readonly string[];
+/** One function of the catalog, as a listing prints it. */
+export interface CatalogFunction {
+    readonly name: string;
+    /**
+     * The signature a human reads, which is not always one registration: an optional
+     * parameter is written `fn(string?): string` and registers one signature per arity.
+     */
+    readonly signature: string;
+    /** Every signature the function registers, in registration order. */
+    readonly signatures: readonly string[];
+    readonly category: string;
+    readonly summary: string;
+    /** False where two calls with the same arguments may answer differently. */
+    readonly deterministic: boolean;
+    /** Whether the implementation is the host's rather than the engine's. */
+    readonly hostBacked: boolean;
+    /** Whether the function refuses an argument written as a literal, at check. */
+    readonly checksLiteralArguments: boolean;
+}
+/** The catalog, as the one surface a listing reads. */
+export declare function functionCatalog(): readonly CatalogFunction[];
+/** Every signature the catalog registers, for a validator and for a docs listing. */
+export declare function catalogSignatures(): readonly string[];
+export interface RegisterCatalogOptions {
+    /**
+     * The implementations of the nine host-backed functions. Each may be left out — the
+     * registration is still made, so an expression calling it still type-checks, and
+     * evaluating one answers an `unbound_function` error naming the function. That is what
+     * a consumer which only ever CHECKS (an analyzer, an editor) needs.
+     */
+    readonly handlers?: Partial<CelCatalogHandlers>;
+}
+/**
+ * Registers the catalog onto an environment, through the public registration surface.
+ *
+ * A signature the runtime table does not answer for is refused here: a declaration with
+ * no behaviour type-checks and then fails at evaluation, which is precisely the failure
+ * the declaration/behaviour split exists to catch at registration instead.
+ */
+export declare function registerFunctionCatalog(environment: CelEnvironment, options?: RegisterCatalogOptions): void;
+//# sourceMappingURL=function-catalog.d.ts.map

package/dist/function-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-catalog.d.ts","sourceRoot":"","sources":["../src/function-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAwBvD,eAAO,MAAM,2BAA2B,QAAkB,CAAC;AAE3D,oFAAoF;AACpF,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAErD;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED,uDAAuD;AACvD,wBAAgB,eAAe,IAAI,SAAS,eAAe,EAAE,CAW5D;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAErD;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,cAAc,EAC3B,OAAO,GAAE,sBAA2B,GACnC,IAAI,CAyBN"}

package/dist/function-catalog.js

@@ -0,0 +1,77 @@
+/**
+ * Loading the function catalog into an environment.
+ *
+ * The catalog is the **dialect**: the functions a manifest may call beside CEL's own
+ * library. Like the standard library it is **data** (`signatures/function-catalog.json`)
+ * read through the same registration surface a host uses — here literally the public one,
+ * `CelEnvironment.registerFunction`, with no privileged door of any kind. A host may
+ * register the catalog, leave it out, replace one of its signatures or remove a name, and
+ * nothing in the engine behaves differently for it.
+ *
+ * **One surface, read by everything that lists the catalog.** `functionCatalog()` answers
+ * each function with its display signature, its category, its summary and its two flags,
+ * which is exactly what a `functions` listing prints; a consumer never reconstructs that
+ * from registrations.
+ *
+ * What a function DOES is beside it, per runtime — `catalog-runtime.ts`, keyed by the same
+ * dispatch key the registry resolves on. A declared signature with no behaviour there is
+ * refused at registration rather than at evaluation, which is the failure class the two
+ * artifacts exist to remove.
+ */
+import data from "./signatures/function-catalog.json" with { type: "json" };
+import { catalogImplementation, catalogLiteralCheck } from "./catalog-runtime.js";
+import { parseSignature, signatureKey } from "./signature.js";
+const DATA = data;
+export const FUNCTION_CATALOG_GENERATION = DATA.generation;
+/** The categories the catalog groups its functions under, for a grouped listing. */
+export function catalogCategories() {
+    return DATA.categories;
+}
+/** The catalog, as the one surface a listing reads. */
+export function functionCatalog() {
+    return DATA.functions.map((entry) => ({
+        name: entry.name,
+        signature: entry.signature,
+        signatures: entry.signatures,
+        category: entry.category,
+        summary: entry.summary,
+        deterministic: entry.deterministic,
+        hostBacked: entry.hostBacked,
+        checksLiteralArguments: entry.checksLiteralArguments ?? false,
+    }));
+}
+/** Every signature the catalog registers, for a validator and for a docs listing. */
+export function catalogSignatures() {
+    return DATA.functions.flatMap((entry) => entry.signatures);
+}
+/**
+ * Registers the catalog onto an environment, through the public registration surface.
+ *
+ * A signature the runtime table does not answer for is refused here: a declaration with
+ * no behaviour type-checks and then fails at evaluation, which is precisely the failure
+ * the declaration/behaviour split exists to catch at registration instead.
+ */
+export function registerFunctionCatalog(environment, options = {}) {
+    const handlers = options.handlers ?? {};
+    for (const entry of DATA.functions) {
+        const check = entry.checksLiteralArguments ? catalogLiteralCheck(entry.name) : undefined;
+        if (entry.checksLiteralArguments && check === undefined) {
+            throw new Error(`the catalog declares that ${entry.name} checks its literal arguments, and no guard answers for it`);
+        }
+        for (const signature of entry.signatures) {
+            const key = signatureKey(parseSignature(signature));
+            const implementation = catalogImplementation(key, handlers);
+            if (implementation === undefined) {
+                throw new Error(`the catalog declares ${signature} and nothing implements ${key}`);
+            }
+            environment.registerFunction(signature, {
+                implementation,
+                deterministic: entry.deterministic,
+                hostBacked: entry.hostBacked,
+                description: entry.summary,
+                origin: "function-catalog",
+                ...(check === undefined ? {} : { checkArguments: check }),
+            });
+        }
+    }
+}