@telorun/cel 0.0.0-stage → 0.107.0

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 CodeNet Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
+# @telorun/cel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Common Expression Language, as a library: read an expression, hold it as a tree, check it, run it,
+compile it to JavaScript, write it back.
+
+```ts
+import { parseExpression, qualifiedCalls, rootReferences, serializeTree } from "@telorun/cel";
+
+const expression = parseExpression("Billing.total(cart.items)", { namespaces: ["Billing"] });
+
+expression.diagnostics; // [] — nothing it could not read
+rootReferences(expression.root); // ["cart"] — what it reads from its environment
+qualifiedCalls(expression.root); // one call: Billing.total, arity 1, with its range
+serializeTree(expression.root); // "Billing.total(cart.items)"
+```
+
+## What it answers
+
+- **The whole expression grammar**, into a tree whose every node carries the `[start, end]` span of
+  source it covers: int64, `u`-suffixed uint64 and double literals; single-, double- and
+  triple-quoted strings, raw strings, `b"…"` and `br"…"` bytes, with every escape CEL defines; `true`,
+  `false`, `null`; list and map literals; the operator precedence table; member access and index access
+  in both their plain and optional forms (`.`, `.?`, `[]`, `[?]`), a member name between backticks, and
+  a name a dot opens (`.y`); global calls and receiver calls.
+- **Qualified calls.** `Alias.fn(x)` and `obj.method(x)` are the same syntax, so the only thing that
+  can tell them apart is a set of names that denote namespaces. Pass that set as `namespaces` and
+  every call on one of those names becomes a `qcall` node. An expression records the set it was
+  resolved under, so a consumer can tell whether it is looking at a tree resolved for its own site.
+- **Error recovery.** Reading never throws. A malformed or half-typed expression gives back a tree
+  for the longest prefix that read, plus one diagnostic with the range of what stopped it — a member
+  with no name yet (`request.`) is a select with an empty field, which is what completion after a dot
+  needs.
+- **Round-trip.** `serializeTree` writes any tree back as source that reads as an equal expression
+  (`treesEqual`), parentheses placed from precedence rather than remembered from the text.
+- **Two questions about a tree**: `rootReferences` — the first name of every access chain, excluding
+  what a comprehension or `cel.bind` binds and excluding a namespace; and `qualifiedCalls` — every
+  call on a namespace, in source order.
+- **Input limits.** 100000 nodes, 250 levels of nesting, 1000 list elements, 1000 map entries and 32
+  call arguments, each reported as an ordinary diagnostic rather than an exception, so hostile input
+  behaves like any other unreadable input. `DEFAULT_PARSE_LIMITS` are those numbers; pass `limits` to
+  change them.
+
+## Checking
+
+```ts
+import { CelEnvironment } from "@telorun/cel";
+
+const environment = new CelEnvironment({ enableOptionalTypes: true })
+  .registerVariable("request", { schema: requestSchema })   // typed to full depth
+  .registerFunction("sha256(string): string", { hostBacked: true, throws: ["ERR_DIGEST_FAILED"] })
+  .registerNamespace("Billing", ["total(int, int): int"]);
+
+const result = environment.check("request.query.limti");
+result.valid;        // false
+result.diagnostics;  // [{ code: "CEL_UNKNOWN_FIELD", message: "…(declared: limit, tags)", range: [14, 19] }]
+result.calls;        // which signature each call resolved to, with its metadata
+environment.check("request.query.limit").typeName; // "int"
+```
+
+- **Registration is not privileged.** CEL's own library registers through the same `registerFunction`,
+  and the dispatch key is a call's name, form and parameter types — not its return type. So
+  `registerFunction("duration(string): Money")` **replaces** the library's `duration(string)`, and
+  `removeFunctionsNamed("duration")` makes a call to it `CEL_UNKNOWN_FUNCTION`. `clone()` inherits
+  everything and then diverges.
+- **JSON Schema is the native input, to full depth** — nested objects, element types, unions kept as
+  unions, `allOf` intersected, and a reference followed. A flat field map (`{ fields: { columns: "map" } }`)
+  is still accepted, for a host that must type exactly as shallowly as something it is replacing.
+- **Nothing a schema says falls through to `dyn` in silence.** A `#/$defs/…` reference is resolved against
+  the document the node belongs to; one that leaves the document is answered by the host's own resolver,
+  which returns a registered type name **or the document to read in place of that node**. A node the
+  engine has no rule for is **reported** by JSON Pointer rather than typed `dyn` quietly —
+  `environment.schemaReports()`, so the consumer that knows where the schema was written can anchor a
+  diagnostic at that line. A reference re-entered on the descent is a recursive schema: the one deliberate
+  `dyn`, declared as such.
+- **A named type is not its base.** `registerType({ name: "Money", base: "int" })` gives a type its own
+  operators, comparisons, conversions, members and invariant type parameters; a plain `int` is refused at
+  a `Money` slot, and `Holder<string>` where `Holder<int>` is wanted is `CEL_TYPE_ARGUMENT_MISMATCH`.
+- **Every verdict carries a range and is decided by the checker** — `CEL_SYNTAX_ERROR`,
+  `CEL_TYPE_ERROR`, `CEL_UNKNOWN_IDENTIFIER`, `CEL_UNKNOWN_FIELD`, `CEL_UNKNOWN_FUNCTION`,
+  `CEL_WRONG_CALL_FORM`, `CEL_TYPE_ARGUMENT_MISMATCH`, `CEL_NULLABLE_ACCESS`, `CEL_INVALID_ARGUMENT`, and
+  `FUNCTION_UNRESOLVED` / `FUNCTION_ARITY_MISMATCH` / `FUNCTION_ARGUMENT_MISMATCH` for a namespaced call.
+  A fix, where one is offered, is the whole corrected source.
+- **A namespaced call is judged only against what you declared.** `registerNamespace("Billing", […],
+  { open: true })` makes a name you did not declare type `dyn` and report nothing — it is still **listed**
+  in `result.calls`, so you resolve it against your own vocabulary and word that verdict yourself. And a
+  declaration written `{ name: "total", returns: "double" }` instead of `{ signature }` withholds the
+  parameter list: the result is typed, the arity and argument types are yours to judge. Both are for a host
+  whose resolution or whose signature grammar is richer than CEL's; neither can be half-declared, since
+  there is no way to supply parameters and ask for them to be ignored.
+- **Three guards clear a read of something that may be null** and no others: `?:`, `&&`, `||`.
+- **The optional library enters whole** where `enableOptionalTypes` is on: `.?`, `[?]`, `[?x]`,
+  `{?k: v}`, `optional.of`, `none`, `ofNonZeroValue`, `hasValue`, `value`, `or`, `orValue`, `optMap`,
+  `optFlatMap`, equality over optionals, `type()` of one, and the type name `optional_type`.
+- **A member whose name is not an identifier is read between backticks** —
+  `request.headers.`` `content-type` ``, typed against the schema's `properties` exactly as a plain
+  member is, so a typo in a dashed or dotted key is still `CEL_UNKNOWN_FIELD`. Only where a member is
+  read: anywhere else a backtick is a syntax error.
+- **A dotted declaration is one name.** Declare `a.b.c`, or `a.b`, or both: `a.b.c` reads the variable of
+  that name where it is declared and the map's entry where only `a.b` is — the longest prefix wins.
+- **`.y` resolves against the environment**, never against a name the expression bound: it is the only
+  spelling for an outer name where a comprehension variable shares it.
+- `convertsToString(type)` answers whether a value of that type can be rendered as text by the
+  environment's own `string()`.
+
+The standard library is data — `src/signatures/standard-library.json`, described in
+[docs/signature-data.md](docs/signature-data.md). It is **CEL's** library: a declaration CEL itself does
+not define carries `"spec": false` and a reason saying why it is here, where the equivalent lives and how
+this member differs from it — and nineteen do.
+
+## The function catalog
+
+Beside CEL's own library there is a second one — Telo's dialect, 67 functions over 86 signatures, also
+data (`src/signatures/function-catalog.json`):
+
+```ts
+import { CelEnvironment, functionCatalog, registerFunctionCatalog } from "@telorun/cel";
+
+const environment = new CelEnvironment({ enableOptionalTypes: true });
+registerFunctionCatalog(environment, {
+  handlers: { sha256: hashHex, json: writeJson, joinPath: (base, rest) => join(base, rest) },
+});
+
+environment.evaluate("formatDuration(510, 480)"); // "1d 30m"
+functionCatalog();                                // the one listing surface: name, signature, category, summary, flags
+```
+
+- **It registers through the public surface** — `registerFunction`, once per signature — so it can be
+  left out, replaced function by function, or removed by name. A default environment has none of it.
+- **Nine functions are the host's**: `sha256`, `md5`, `sha1`, `sha512`, `hmac`, `base64Encode`,
+  `base64Decode`, `json` and `joinPath`, each needing a facility this package may not reach. One left
+  out still registers, so a consumer that only checks still type-checks the call; evaluating it answers
+  `unbound_function` naming the function.
+- **A refusal is the catalog's own words**, `<function>: <what is wrong>` — never a library's wording.
+  An invalid pattern ends with one of RE2's own parse-error kinds and nothing after it, and `parseJson`
+  words its own offset (`parseJson: invalid JSON at offset 3`).
+- **A literal argument is refused at CHECK**, not only when the expression runs: `fixed(1.0, 11)` is
+  `CEL_INVALID_ARGUMENT` naming the call, because a signature constrains types and a decimal count out
+  of range is a value. Twelve functions carry such a guard, and each runs the very code the evaluation
+  runs.
+- **Two families reach a host facility by declaration** — the clock (`now`, `nowIso`, `today`,
+  `nowMillis`, `nowSeconds`) and the random source behind the UUID functions, which is what
+  `deterministic: false` means. Both exist in a browser as in Node.
+
+## Evaluating
+
+```ts
+const program = environment.compile("request.query.limit != null ? int(request.query.limit) : 25");
+
+program.evaluate({ request: { query: { limit: "50" } } }); // 50n
+program.evaluate({ request: { query: {} } });              // 25n
+```
+
+- **Every operator and function behaves as cel-spec requires.** `int` is a `bigint` and an overflow is
+  an error rather than a wrap; `uint` and `double` are distinct types; division and modulus by zero are
+  two different errors; bytes and strings are distinct and both are ordered; a timestamp is
+  nanosecond-precise and its getters take a zone (an IANA name or a fixed `HH:MM` offset); `matches` is
+  RE2, so a pattern the host's own engine would accept and RE2 would not is refused.
+- **A duration is the signed 64-bit range of its total nanoseconds** —
+  `-9223372036.854775808s … 9223372036.854775807s`, roughly ±292 years, which is cel-spec's own limit.
+  It is checked wherever a duration is built: the conversion, duration `+` and `-`, `timestamp -
+  timestamp`, and the duration operand of `timestamp ± duration`. A host's own duration format may be
+  wider — `google.protobuf.Duration` is ±10,000 years — and CEL's is a subrange of it, so a duration a
+  transport can carry is not always one CEL can construct.
+- **Eight string members are not CEL's**, and each says so in its own declaration (`"spec": false` with a
+  reason): `indexOf`, `lastIndexOf` and `substring` index by **UTF-16 code unit** rather than by code
+  point, `lowerAscii` and `upperAscii` apply the host language's casing rather than touching the ASCII
+  letters alone, and `trim`, `split` and `join` differ from the strings extension's equivalents in the
+  ways their reasons name. `size`, `startsWith`, `endsWith`, `contains`, `matches` and concatenation are
+  CEL's own.
+- **An error is a VALUE that participates in short-circuit.** `false && <missing key>` is `false` and
+  `true || <missing key>` is `true`, from either side; an error that survives to the top of an
+  evaluation becomes a thrown `CelEvaluationError` carrying one of the codes in `CEL_EVALUATION_CODES`
+  (`no_such_key`, `numeric_overflow`, `division_by_zero`, `modulo_by_zero`, `index_out_of_range`,
+  `invalid_regular_expression`, `invalid_conversion`, `optional_value_missing`,
+  `async_value_unsupported`, …) and the range of the text it is about.
+- **Evaluation is synchronous**, and a value that must be awaited is refused at **every door it comes
+  through**: an activation read, a registered implementation's result, a member read in any form, an
+  element entering a comprehension body, the value `cel.bind` binds, an optional's held value, and list
+  membership. Each answers `async_value_unsupported`, never a value passed along and never an answer
+  decided about a value nothing touched: the element is refused where it is **bound**, and that refusal is
+  terminal — `xs.all(e, false)` and `xs.exists(e, true)` over a list holding a promise refuse rather than
+  answering off the one element that is readable, while an ordinary `no_such_key` still short-circuits as
+  before. A container is deliberately not walked, so `size(xs)` and `xs + [3]` carry it along and every
+  way of reading the element out is refused.
+- **A value says what it is by a string type key** under `Symbol.for("telo.cel.value")`, never by its
+  constructor, so two copies of the engine agree about a value either of them built. `null`, a boolean,
+  a string, a `number` (double), a `bigint` (int), a `Uint8Array` (bytes), an array (list) and a plain
+  object (a string-keyed map) carry no key; a uint, a timestamp, a duration, a type value, an optional,
+  a map with typed keys and an error do. A plain object carrying a string-keyed look-alike brand is
+  data, as it must be.
+- **Every member read goes through one lookup** over the value's own entries — `a.b`, `a['b']`,
+  `a[expr]`, `.?`, `[?]` and a macro's field read alike — so no key, however it was computed, reaches a
+  prototype, a method or a function property. A CEL map is built prototype-free, so `__proto__`,
+  `constructor` and `prototype` round-trip as data.
+- **No `eval`, no `new Function`, no disk.** `compile` builds a tree of closures over the runtime
+  library, which is where every operator lives exactly once. In-process caches — compiled expressions
+  per environment, compiled patterns, a call site's resolved overloads — are bounded, each with a
+  declared capacity.
+- `evaluateToValue` answers the error value instead of throwing, for a caller that carries errors
+  itself. A namespaced call is dispatched through `namespaceFunction`, supplied per evaluation; one
+  nothing binds is `unbound_function`.
+
+## Emitting JavaScript
+
+The same expressions compile to **JavaScript source**, as one module for a set of them:
+
+```ts
+const module = environment.emit(["a + b * 2", "xs.map(e, e * 2)"]);
+
+module.key;    // 64 hexadecimal characters: what a host names its stored copy by
+module.text;   // the module's source, which imports nothing
+module.header; // { format, engine, environment, key, body } — the header line's own fields
+
+// A host loads it however it loads a module, then:
+const programs = programsFromEmittedModule(loaded, module, environment.emitterRuntime());
+programs[0].evaluate({ a: 3n, b: 4n }); // 11n
+```
+
+- **Both backends answer identically, case for case** — the same value, or the same error code and the
+  same range. That is a property of the wiring rather than of the tests: every operator, comprehension,
+  member read, name read, bool operand and call-site dispatch is one function both backends call, so the
+  only thing the two compile differently is how control gets from one call to the next.
+- **The runtime is the factory's argument, never an import.** The module's default export takes the
+  runtime support library and answers one synchronous function per expression, and the text names no
+  specifier — so it loads from a `data:` URL, from a cache directory mounted anywhere, and under a host
+  whose resolver is not Node's. A module importing a package would also accept a runtime of another
+  version silently, which the key could not see.
+- **The key covers the environment, not just the source.** It hashes the emitter's format generation, the
+  engine version, the environment's digest and the ordered list of expression sources. The digest is over
+  the environment's **resolved listing** — every surviving function signature, every named type, every
+  variable, every namespace, every option — so two environments built by different registration orders
+  are one key, and a host that replaced or removed a standard function is a different one.
+- **The header is verified before anything runs, and it is five fields rather than three.** `format`,
+  `engine` and `environment` are provenance, and they are byte-identical for every module one engine
+  writes against one environment — so `key` (the module's own identity) and `body` (the digest of
+  everything after the header line) are what catch a store that answered the wrong lookup, a text
+  truncated after its header, and a text edited after it was written. `body` covers the `integrity`
+  export and so cannot live in it: the header line carries all five, the export carries the four a loaded
+  object can be held to. Every mismatch a stored **text** shows is a recompile naming itself under
+  `refused`; a loaded **module** that declares nothing, declares another key or answers the wrong number
+  of functions is refused with `CelEngineError` (`emitted_module_rejected`).
+- **One store seam, and no loader.** `environment.emittedModule(sources, store)` reads and writes module
+  text by key through an interface the host supplies; the engine touches no filesystem, and a hit parses
+  nothing. A store's write should be **atomic** — written elsewhere, then renamed — because several hosts
+  share one cache root; that is how a half-written entry is avoided, and the `body` digest is how one is
+  detected if it is not.
+- **Emission is deterministic**: the same expressions in the same order against the same environment are
+  the same bytes.
+- It is **faster, not differently behaved** — and by exactly one thing: what the closure calls cost.
+  Both backends pay the same shared runtime underneath, so an expression whose cost is a dotted-chain
+  search and a conversion is a wash, while one that calls many small operations gains.
+
+## What it deliberately does not do
+
+- **Nothing is expanded at read time.** `has(x)`, `xs.map(i, i)` and `cel.bind(x, 1, x)` are ordinary
+  call nodes in the tree; the checker lowers them, so the source stays writable from the tree.
+- **It knows no host's vocabulary.** No type name, no annotation, no manifest word: a host registers
+  its own through `registerType` and one schema resolver. The function catalog above is a set of
+  functions over CEL's own types — no signature in it names a host type — which is what a dialect is.
+- **It never type-checks on its way to evaluating.** The checker decides every verdict and a consumer
+  asks for them; compiling refuses only what cannot be compiled at all — a source that did not read
+  whole.
+- **The LANGUAGE reaches no host facility.** No filesystem, no clock, no network, no Node built-in — it
+  runs unchanged in a browser, and so does the catalog: its clock and UUID functions read facilities
+  every host has, and its nine host-backed functions reach nothing at all by themselves.
+
+## Reserved words
+
+CEL reserves 21 words, and none of them can be read as a name: `as break const continue else false for
+function if import in let loop namespace null package return true var void while`. Seventeen are refused
+outright; `true`, `false` and `null` are literals where they stand, and `in` is the membership operator,
+which is why a name position can never reach them.
+
+A reserved word is still a legal **member** name — `{'let': 1}.let`, `a.while()`, `a.in`, `a.true` — which
+is CEL's own rule: a member names an entry of a value, not a name in the expression's scope.
+
+Nothing is reserved on a host's behalf: `__proto__`, `prototype` and `constructor` are ordinary names.
+Keeping a host's own properties out of a CEL value is the member read's job, not a word list's — a
+member key can be computed (`a[request.query.k]`), which no list of names would judge.
+
+`cel` and `optional` are ordinary identifiers, but can never be registered as a namespace: the
+standard macros are written on them.

package/dist/activation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The activation: the values an expression reads names from.
+ *
+ * Two rules, both of which the checker already applies to types, so the evaluator must
+ * apply them to values or `telo check` and the runtime disagree:
+ *
+ * - **A dotted declaration is one name, and the longest one wins.** A host may hold
+ *   `a.b.c`, or `a.b` holding a map, or both; `a.b.c` reads the entry of that name where
+ *   it is held and the map's entry where only `a.b` is. So resolution tries the longest
+ *   prefix first, exactly as `qualifiedVariableType` does at check.
+ * - **A read is an OWN entry**, never an inherited one, so an activation whose prototype
+ *   is `Object.prototype` cannot answer `constructor` or `toString`.
+ *
+ * A name nothing holds is `no_such_variable` — the error value, so it short-circuits like
+ * any other. A value read from here is a HOST's, so it is admitted through the backend's
+ * one entry point for a host value, which is where a thenable is refused.
+ */
+/** What a host binds names to. A value is read through the guard below, never trusted. */
+export interface CelActivation {
+    readonly [name: string]: unknown;
+}
+/**
+ * Whether the activation holds a name itself. The backend asks this for each prefix of a
+ * dotted chain, longest first, having built the prefixes once at compile time.
+ */
+export declare function activationHolds(activation: CelActivation, name: string): boolean;
+//# sourceMappingURL=activation.d.ts.map

package/dist/activation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../src/activation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhF"}

package/dist/activation.js

@@ -0,0 +1,24 @@
+/**
+ * The activation: the values an expression reads names from.
+ *
+ * Two rules, both of which the checker already applies to types, so the evaluator must
+ * apply them to values or `telo check` and the runtime disagree:
+ *
+ * - **A dotted declaration is one name, and the longest one wins.** A host may hold
+ *   `a.b.c`, or `a.b` holding a map, or both; `a.b.c` reads the entry of that name where
+ *   it is held and the map's entry where only `a.b` is. So resolution tries the longest
+ *   prefix first, exactly as `qualifiedVariableType` does at check.
+ * - **A read is an OWN entry**, never an inherited one, so an activation whose prototype
+ *   is `Object.prototype` cannot answer `constructor` or `toString`.
+ *
+ * A name nothing holds is `no_such_variable` — the error value, so it short-circuits like
+ * any other. A value read from here is a HOST's, so it is admitted through the backend's
+ * one entry point for a host value, which is where a thenable is refused.
+ */
+/**
+ * Whether the activation holds a name itself. The backend asks this for each prefix of a
+ * dotted chain, longest first, having built the prefixes once at compile time.
+ */
+export function activationHolds(activation, name) {
+    return Object.prototype.hasOwnProperty.call(activation, name);
+}

package/dist/backend-runtime.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What a backend does at each kind of site — once, for both of them.
+ *
+ * `runtime-library.ts` holds what every operator and standard function **does**. This
+ * holds everything *around* a call: admitting a host value, reading a member in every
+ * form, taking a bool operand, reading a name or a dotted chain, and the per-call-site
+ * overload dispatch with its bounded cache. None of it is a tree walk and none of it is an
+ * operator, which is exactly why it cannot live in a backend: the closure backend compiles
+ * a tree to closures and the emitter compiles the same tree to JavaScript source, and both
+ * call *these* functions. A second copy of the dispatch rule or the member-read rule is a
+ * second set of answers, and the whole point of two backends over one runtime is that
+ * there is one answer per operation.
+ *
+ * So the emitter emits a call to `readThrough` and never a bare `obj.name`; it emits a
+ * `CallSite` per call and never its own overload search; and a thenable is refused at the
+ * same doors on both backends because the doors are here.
+ */
+import type { CelActivation } from "./activation.js";
+import type { CelType } from "./cel-type.js";
+import type { CelError, CelOptional, CelValue } from "./cel-value.js";
+import type { FunctionRegistry } from "./function-registry.js";
+import type { CelImplementation } from "./runtime-library.js";
+import type { CallForm } from "./signature.js";
+import type { CelSelectNode, SourceRange } from "./syntax-tree.js";
+/** A compile-time refusal: a tree neither backend can compile at all. */
+export declare class CelCompileError extends Error {
+    constructor(message: string);
+}
+/** How many distinct argument-type combinations one call site remembers. */
+export declare const CALL_SITE_CACHE_CAPACITY = 16;
+/** What a namespaced call is dispatched through, when something bound it. */
+export type NamespaceDispatch = (namespace: string, name: string) => CelImplementation | undefined;
+export interface EvaluationFrame {
+    readonly activation: CelActivation;
+    readonly slots: CelValue[];
+    /** Absent rather than optional: one frame shape, however the evaluation was started. */
+    readonly namespaceFunction: NamespaceDispatch | undefined;
+}
+/**
+ * One evaluation of one expression. The closure backend builds these by composition and
+ * the emitter's module returns them already built, so a program is indifferent to which
+ * backend produced it.
+ */
+export type CelStep = (frame: EvaluationFrame) => CelValue;
+/** What a backend needs of the environment it compiles against. */
+export interface CompileTarget {
+    readonly registry: FunctionRegistry;
+    /** The library's own names — the type values and `google`. */
+    readonly constants: ReadonlyMap<string, CelValue>;
+    /** How many type arguments a host's named type takes, for dispatch on one of its values. */
+    readonly nominalArity: (name: string) => number | undefined;
+    /**
+     * Whether a host DECLARED this name — including a dotted one. It decides where a chain
+     * splits, at compile time, through the same function the checker uses.
+     */
+    readonly declares: (name: string) => boolean;
+}
+/**
+ * A host value entering the engine — from an activation, from an implementation the host
+ * registered, or out of a host value a read reached into. A thenable is refused here rather
+ * than carried: an awaiting expression is an invocation in disguise, invisible to a journal
+ * and absent from a trace. The refusal itself lives in `cel-value.ts`, so every door answers
+ * with the same code and the same wording.
+ */
+export declare function readHostValue(value: unknown, range: SourceRange): CelValue;
+/** A bare name: the activation's own entry, then the library's constants. */
+export declare function readName(activation: CelActivation, constants: ReadonlyMap<string, CelValue>, name: string, range: SourceRange): CelValue;
+/**
+ * One name read from the activation (or the library's constants), then its members. This
+ * is a chain whose split is already decided — at compile time, over the names the host
+ * declared (`declared-chain.ts`) — so evaluating it is one lookup plus member reads.
+ */
+export declare function readNameChain(activation: CelActivation, constants: ReadonlyMap<string, CelValue>, name: string, rest: readonly string[], range: SourceRange): CelValue;
+/** One prefix of a dotted chain, and the segments left to read off its value. */
+export interface ChainCandidate {
+    readonly name: string;
+    readonly rest: readonly string[];
+}
+/** Every prefix of a dotted chain, longest first, with the segments left to read. */
+export declare function prefixCandidates(segments: readonly string[]): readonly ChainCandidate[];
+/**
+ * A chain **no** prefix of which the host declared: the activation is searched, longest
+ * prefix first. Every conformance row that binds a dotted key reads this way, and the
+ * checker has no opinion about such a chain either.
+ */
+export declare function searchNameChain(activation: CelActivation, constants: ReadonlyMap<string, CelValue>, candidates: readonly ChainCandidate[], written: string, range: SourceRange): CelValue;
+/**
+ * The dotted chain a select spells, when every step is a plain named member of a **free**
+ * name. A name a macro bound is a value, so a chain rooted at one is an ordinary member
+ * read — the same rule the checker applies, and the same answer both backends compile.
+ */
+export declare function plainMemberChain(node: CelSelectNode, bound: (name: string) => boolean): readonly string[] | undefined;
+/**
+ * A member read in every form. Reading **through an optional** answers an optional
+ * whichever form the read is written in, which is what lets a chain over a value that
+ * may be absent stay one expression: an absent one propagates as absent, a key the held
+ * value does not have is absent too, and a held value that holds no members at all is
+ * still the mistake it would be outside an optional.
+ */
+export declare function readThrough(container: CelValue, key: CelValue, optionalForm: boolean, range: SourceRange): CelValue;
+/**
+ * `has(a.b)` — presence, which a missing key answers `false` for rather than erroring.
+ * An absent optional has no members, and a present one is asked about what it holds.
+ */
+export declare function hasMember(container: CelValue, field: CelValue, range: SourceRange): CelValue;
+/** A bool operand, or the error it is — a non-bool is a mistake of its own. */
+export declare function boolOperand(value: CelValue, range: SourceRange): boolean | CelError;
+/** What an optional entry of an aggregate contributes, or the error it is not one. */
+export declare function optionalEntry(value: CelValue, range: SourceRange): CelOptional | CelError;
+/**
+ * One call site, and the overloads it has resolved.
+ *
+ * **Overloads are resolved on the values' own types**, per site: `dyn(1.0) == 1` checks and
+ * must then answer across the numeric types, so the statically resolved signature is not
+ * enough. A site is almost always monomorphic, so the last resolution is held beside a
+ * bounded cache and reached by comparing the type names themselves — building a cache key
+ * per call is the allocation that costs most on the hottest path there is. A container's
+ * element type is read as `dyn` rather than walked, so dispatch does not get more expensive
+ * as the data gets larger.
+ *
+ * The arguments arrive **already evaluated and already free of errors**: carrying an
+ * error-valued operand out is the caller's, because only the caller knows how far it got.
+ */
+export declare class CallSite {
+    private readonly name;
+    private readonly form;
+    private readonly range;
+    private readonly registry;
+    private readonly nominalArity;
+    private readonly resolved;
+    private readonly context;
+    private lastNames;
+    private lastDispatch;
+    constructor(name: string, form: CallForm, range: SourceRange, registry: FunctionRegistry, nominalArity: (name: string) => number | undefined);
+    call(values: readonly CelValue[]): CelValue;
+    private answer;
+}
+/** A call site over an environment, which both backends build one of per call. */
+export declare function callSiteOf(target: CompileTarget, name: string, form: CallForm, range: SourceRange): CallSite;
+/**
+ * The type of a value, for dispatch. A container's element type is `dyn`: reading it
+ * exactly would mean walking the data on every call, and the registry's loose pass
+ * resolves a parameterized overload against `dyn` anyway.
+ */
+export declare function runtimeType(value: CelValue, nominalArity: (name: string) => number | undefined): CelType;
+//# sourceMappingURL=backend-runtime.d.ts.map

package/dist/backend-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-runtime.d.ts","sourceRoot":"","sources":["../src/backend-runtime.ts"],"names":[],"mappings":"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"}