@telorun/cel 0.0.0-stage → 0.108.0

package/dist/macro-shape.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether each macro call is shaped like one at all, judged before any type is read.
+ *
+ * A macro's own arguments are not values: `xs.map(i, …)` declares the name `i`, and
+ * `has(a.b)` asks about the member `b` of a chain of names. Neither is something a type
+ * can be wrong about — they are either written in the shape the macro takes, or the call
+ * is not that macro. So this is a **structural** pass over the whole tree, and it runs
+ * first: a macro written wrongly is reported before anything inside it is typed, because
+ * the typing of its body depends on a name the call failed to declare.
+ *
+ * The walk is **post-order**, so the innermost mistake is the one reported first. Nesting
+ * macros is how a generated expression goes wrong, and the inner call is the one a reader
+ * has to fix.
+ */
+import type { CelCheckCode } from "./check-diagnostic.js";
+import type { CelNode, SourceRange } from "./syntax-tree.js";
+export interface MacroShapeFinding {
+    readonly code: CelCheckCode;
+    readonly message: string;
+    readonly range: SourceRange;
+}
+/** Every macro call whose own arguments are not the shape it takes, innermost first. */
+export declare function macroShapeFindings(root: CelNode): readonly MacroShapeFinding[];
+//# sourceMappingURL=macro-shape.d.ts.map

package/dist/macro-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macro-shape.d.ts","sourceRoot":"","sources":["../src/macro-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,iBAAiB,EAAE,CAI9E"}

package/dist/macro-shape.js

@@ -0,0 +1,55 @@
+/**
+ * Whether each macro call is shaped like one at all, judged before any type is read.
+ *
+ * A macro's own arguments are not values: `xs.map(i, …)` declares the name `i`, and
+ * `has(a.b)` asks about the member `b` of a chain of names. Neither is something a type
+ * can be wrong about — they are either written in the shape the macro takes, or the call
+ * is not that macro. So this is a **structural** pass over the whole tree, and it runs
+ * first: a macro written wrongly is reported before anything inside it is typed, because
+ * the typing of its body depends on a name the call failed to declare.
+ *
+ * The walk is **post-order**, so the innermost mistake is the one reported first. Nesting
+ * macros is how a generated expression goes wrong, and the inner call is the one a reader
+ * has to fix.
+ */
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+import { childNodes } from "./syntax-tree.js";
+/** Every macro call whose own arguments are not the shape it takes, innermost first. */
+export function macroShapeFindings(root) {
+    const findings = [];
+    collect(root, findings);
+    return findings;
+}
+function collect(node, findings) {
+    for (const child of childNodes(node))
+        collect(child, findings);
+    const finding = shapeOf(node);
+    if (finding)
+        findings.push(finding);
+}
+function shapeOf(node) {
+    if (node.kind === "call" && node.name === "has" && node.args.length === 1) {
+        const argument = node.args[0];
+        if (argument.kind === "select" && argument.field !== "")
+            return undefined;
+        return {
+            code: "CEL_INVALID_ARGUMENT",
+            message: "has() asks whether a member is there, so it takes a member read: write has(a.b)",
+            range: argument.range,
+        };
+    }
+    if (node.kind !== "receiverCall")
+        return undefined;
+    const binding = receiverMacroBinding(node.name, node.args.length) ??
+        namespaceMacroBinding(node.receiver.kind === "ident" ? node.receiver.name : "", node.name, node.args.length);
+    if (!binding)
+        return undefined;
+    const variable = node.args[binding.variableArgument];
+    if (variable.kind === "ident")
+        return undefined;
+    return {
+        code: "CEL_INVALID_ARGUMENT",
+        message: `${node.name} binds a name here, and this is not a name`,
+        range: variable.range,
+    };
+}

package/dist/member-read.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The member-read seam: **one** lookup, for every form a read is written in.
+ *
+ * `a.b`, `a['b']`, `a[expr]`, `a.?b`, `a[?expr]`, a macro's field read and the presence
+ * question `has()` all resolve here, through a single lookup over the value's **own**
+ * entries. Neither backend ever performs a host property read, so no key — however it
+ * was computed — can reach a prototype, a method or a function property: `a['length']`
+ * on a map is a missing key, not `0`, and `a[request.query.k]` cannot reach
+ * `constructor`.
+ *
+ * That is why the reserved-word set holds CEL's own words and nothing else. A word list
+ * is the wrong instrument: a member *name* is written by the author, while a member
+ * *key* can come from a request, so no list at any position touches the form an
+ * attacker can actually reach — and refusing `__proto__` as a name would make a
+ * resource that may legally be called that unreadable through CEL.
+ *
+ * A key the value does not hold is the `no_such_key` **error value**, which
+ * participates in short-circuit. Never `undefined` passed along.
+ *
+ * **What each of the four verdicts answers is written once here**, in `lookupAbsence`,
+ * and read by both presence callers — so the closure backend, the emitter and the
+ * `has()` macro cannot differ by construction.
+ */
+import type { CelValue } from "./cel-value.js";
+import { type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+/**
+ * What one lookup found. The four refusals are **symbols**, not objects: a lookup happens
+ * on nearly every evaluation, and a wrapper object per read is an allocation per read.
+ * `MISSING` is a key the container does not hold — which `has()` answers `false` for and a
+ * read turns into `no_such_key`; the other three are mistakes in the read itself.
+ */
+export declare const MISSING: unique symbol;
+export declare const OUT_OF_RANGE: unique symbol;
+export declare const UNSUPPORTED_CONTAINER: unique symbol;
+export declare const UNSUPPORTED_KEY: unique symbol;
+export type Lookup = CelValue | typeof MISSING | typeof OUT_OF_RANGE | typeof UNSUPPORTED_CONTAINER | typeof UNSUPPORTED_KEY;
+/**
+ * The single lookup. It is total over the value domain: a container that holds no members
+ * at all answers `UNSUPPORTED_CONTAINER` rather than falling back to a property read that
+ * might find `length`, `name`, `call` or `apply`.
+ */
+export declare function celLookup(container: CelValue, key: CelValue): Lookup;
+/** The value at a key, or the error a failed lookup is. */
+export declare function celRead(container: CelValue, key: CelValue, range?: SourceRange): CelValue | CelError;
+/**
+ * Whether a lookup that found nothing answers **absence** rather than an error. This is
+ * the seam's contract, in the one place both backends and the emitter read it: they all
+ * reach a member read through `backend-runtime.ts`, which reaches the four verdicts
+ * through here.
+ *
+ * - A **presence-shaped** read — `a.?b`, `a[?k]` and `has(a.b)` — answers absence for
+ *   *missing*, *out of range* and *holds no members* alike, and the error only for an
+ *   **unusable key**. It asks whether a member is THERE, and a value that cannot hold one
+ *   has none to find. The authority is the optional library's own: it enters this engine
+ *   from cel-go whole, and cel-go's attribute qualification answers "not found" for a
+ *   receiver that is neither a mapper, a lister nor an indexer **whenever the read is a
+ *   presence test**, erroring only otherwise — the error reading being an explicitly named
+ *   opt-in (`EnableErrorOnBadPresenceTest`), which Telo does not carry, because a
+ *   per-environment switch over what an expression MEANS would let the analyzer and a
+ *   kernel disagree about one manifest.
+ * - A read **through a present optional, written in the ordinary form** — the `.c` of
+ *   `a.?b.c` — is not a presence question about `c`. It answers absence for a key the held
+ *   value does not hold (`optional.of({'c': {}}).c.missing` is absent, cel-spec's
+ *   `optional_chaining_5`) and the error for a held value that holds no members at all
+ *   (`{true: dyn(0)}[?true].absent` is cel-spec's error).
+ * - A **plain** read never asks: each of the four is the error `lookupError` words.
+ *
+ * An unusable key is the one refusal no form forgives: `[?3.1]` names an entry no
+ * container of that shape could hold, so it is a mistake in the READ rather than a member
+ * that happens to be absent.
+ */
+export declare function lookupAbsence(found: symbol, presence: boolean): boolean;
+/** The error a refused lookup is. */
+export declare function lookupError(found: symbol, key: CelValue, range?: SourceRange): CelError;
+/**
+ * Whether a key is there — `has(a.b)`. The question is presence-shaped, so a value that
+ * holds no members answers `false` exactly as a missing key does: it has no member to
+ * find. Only an unusable key is a mistake in the question itself.
+ */
+export declare function celHas(container: CelValue, key: CelValue, range?: SourceRange): boolean | CelError;
+/**
+ * The elements a comprehension ranges over: a list's items, a map's keys. A list is handed
+ * over as it is — nothing in CEL mutates a value, and every comprehension reads its range —
+ * so copying it would cost the length of the list per comprehension to defend against a
+ * write no expression can perform.
+ */
+export declare function celIterable(container: CelValue, range?: SourceRange): readonly CelValue[] | CelError;
+//# sourceMappingURL=member-read.d.ts.map

package/dist/member-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-read.d.ts","sourceRoot":"","sources":["../src/member-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAA8C,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,OAAO,eAA+B,CAAC;AACpD,eAAO,MAAM,YAAY,eAAkC,CAAC;AAC5D,eAAO,MAAM,qBAAqB,eAA4C,CAAC;AAC/E,eAAO,MAAM,eAAe,eAAsC,CAAC;AAEnE,MAAM,MAAM,MAAM,GACd,QAAQ,GACR,OAAO,OAAO,GACd,OAAO,YAAY,GACnB,OAAO,qBAAqB,GAC5B,OAAO,eAAe,CAAC;AAY3B;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,GAAG,MAAM,CAqBpE;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAIpG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAGvE;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,CASvF;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,GAAG,QAAQ,CAKlG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,QAAQ,EAAE,GAAG,QAAQ,CAKpG"}

package/dist/member-read.js

@@ -0,0 +1,166 @@
+/**
+ * The member-read seam: **one** lookup, for every form a read is written in.
+ *
+ * `a.b`, `a['b']`, `a[expr]`, `a.?b`, `a[?expr]`, a macro's field read and the presence
+ * question `has()` all resolve here, through a single lookup over the value's **own**
+ * entries. Neither backend ever performs a host property read, so no key — however it
+ * was computed — can reach a prototype, a method or a function property: `a['length']`
+ * on a map is a missing key, not `0`, and `a[request.query.k]` cannot reach
+ * `constructor`.
+ *
+ * That is why the reserved-word set holds CEL's own words and nothing else. A word list
+ * is the wrong instrument: a member *name* is written by the author, while a member
+ * *key* can come from a request, so no list at any position touches the form an
+ * attacker can actually reach — and refusing `__proto__` as a name would make a
+ * resource that may legally be called that unreadable through CEL.
+ *
+ * A key the value does not hold is the `no_such_key` **error value**, which
+ * participates in short-circuit. Never `undefined` passed along.
+ *
+ * **What each of the four verdicts answers is written once here**, in `lookupAbsence`,
+ * and read by both presence callers — so the closure backend, the emitter and the
+ * `has()` macro cannot differ by construction.
+ */
+import { celMapKeys, mapKeyIdentity } from "./cel-map-value.js";
+import { celError, isCelMap, isCelRecord, isCelUint } from "./cel-value.js";
+/**
+ * What one lookup found. The four refusals are **symbols**, not objects: a lookup happens
+ * on nearly every evaluation, and a wrapper object per read is an allocation per read.
+ * `MISSING` is a key the container does not hold — which `has()` answers `false` for and a
+ * read turns into `no_such_key`; the other three are mistakes in the read itself.
+ */
+export const MISSING = Symbol("cel.lookup.missing");
+export const OUT_OF_RANGE = Symbol("cel.lookup.outOfRange");
+export const UNSUPPORTED_CONTAINER = Symbol("cel.lookup.unsupportedContainer");
+export const UNSUPPORTED_KEY = Symbol("cel.lookup.unsupportedKey");
+/** An int-valued index, or nothing when the value is of no index type. */
+function indexOf(key) {
+    if (typeof key === "bigint")
+        return key;
+    if (isCelUint(key))
+        return key.value;
+    // A double that holds a whole number indexes a list: a `dyn` arithmetic result is a
+    // double, and cel-spec indexes with it where it is integral.
+    if (typeof key === "number" && Number.isInteger(key))
+        return BigInt(key);
+    return undefined;
+}
+/**
+ * The single lookup. It is total over the value domain: a container that holds no members
+ * at all answers `UNSUPPORTED_CONTAINER` rather than falling back to a property read that
+ * might find `length`, `name`, `call` or `apply`.
+ */
+export function celLookup(container, key) {
+    if (typeof key === "string" && isCelRecord(container)) {
+        // An OWN entry, never an inherited one: a host's object is data here.
+        return Object.prototype.hasOwnProperty.call(container, key)
+            ? container[key]
+            : MISSING;
+    }
+    if (isCelMap(container)) {
+        const identity = mapKeyIdentity(key);
+        if (identity === undefined)
+            return UNSUPPORTED_KEY;
+        const entry = container.entries.get(identity);
+        return entry ? entry.value : MISSING;
+    }
+    if (Array.isArray(container)) {
+        const at = indexOf(key);
+        if (at === undefined)
+            return UNSUPPORTED_KEY;
+        if (at < 0n || at >= BigInt(container.length))
+            return OUT_OF_RANGE;
+        return container[Number(at)];
+    }
+    if (isCelRecord(container))
+        return UNSUPPORTED_KEY;
+    return UNSUPPORTED_CONTAINER;
+}
+/** The value at a key, or the error a failed lookup is. */
+export function celRead(container, key, range) {
+    const found = celLookup(container, key);
+    if (typeof found !== "symbol")
+        return found;
+    return lookupError(found, key, range);
+}
+/**
+ * Whether a lookup that found nothing answers **absence** rather than an error. This is
+ * the seam's contract, in the one place both backends and the emitter read it: they all
+ * reach a member read through `backend-runtime.ts`, which reaches the four verdicts
+ * through here.
+ *
+ * - A **presence-shaped** read — `a.?b`, `a[?k]` and `has(a.b)` — answers absence for
+ *   *missing*, *out of range* and *holds no members* alike, and the error only for an
+ *   **unusable key**. It asks whether a member is THERE, and a value that cannot hold one
+ *   has none to find. The authority is the optional library's own: it enters this engine
+ *   from cel-go whole, and cel-go's attribute qualification answers "not found" for a
+ *   receiver that is neither a mapper, a lister nor an indexer **whenever the read is a
+ *   presence test**, erroring only otherwise — the error reading being an explicitly named
+ *   opt-in (`EnableErrorOnBadPresenceTest`), which Telo does not carry, because a
+ *   per-environment switch over what an expression MEANS would let the analyzer and a
+ *   kernel disagree about one manifest.
+ * - A read **through a present optional, written in the ordinary form** — the `.c` of
+ *   `a.?b.c` — is not a presence question about `c`. It answers absence for a key the held
+ *   value does not hold (`optional.of({'c': {}}).c.missing` is absent, cel-spec's
+ *   `optional_chaining_5`) and the error for a held value that holds no members at all
+ *   (`{true: dyn(0)}[?true].absent` is cel-spec's error).
+ * - A **plain** read never asks: each of the four is the error `lookupError` words.
+ *
+ * An unusable key is the one refusal no form forgives: `[?3.1]` names an entry no
+ * container of that shape could hold, so it is a mistake in the READ rather than a member
+ * that happens to be absent.
+ */
+export function lookupAbsence(found, presence) {
+    if (found === MISSING || found === OUT_OF_RANGE)
+        return true;
+    return presence && found === UNSUPPORTED_CONTAINER;
+}
+/** The error a refused lookup is. */
+export function lookupError(found, key, range) {
+    if (found === MISSING)
+        return celError("no_such_key", `no such key: ${describe(key)}`, range);
+    if (found === OUT_OF_RANGE) {
+        return celError("index_out_of_range", `index out of range: ${describe(key)}`, range);
+    }
+    if (found === UNSUPPORTED_KEY) {
+        return celError("unsupported_key_type", `${describe(key)} cannot name an entry of this value`, range);
+    }
+    return celError("unsupported_container", "this value holds no members", range);
+}
+/**
+ * Whether a key is there — `has(a.b)`. The question is presence-shaped, so a value that
+ * holds no members answers `false` exactly as a missing key does: it has no member to
+ * find. Only an unusable key is a mistake in the question itself.
+ */
+export function celHas(container, key, range) {
+    const found = celLookup(container, key);
+    if (typeof found !== "symbol")
+        return true;
+    if (lookupAbsence(found, true))
+        return false;
+    return lookupError(found, key, range);
+}
+/**
+ * The elements a comprehension ranges over: a list's items, a map's keys. A list is handed
+ * over as it is — nothing in CEL mutates a value, and every comprehension reads its range —
+ * so copying it would cost the length of the list per comprehension to defend against a
+ * write no expression can perform.
+ */
+export function celIterable(container, range) {
+    if (Array.isArray(container))
+        return container;
+    if (isCelMap(container))
+        return celMapKeys(container);
+    if (isCelRecord(container))
+        return Object.keys(container);
+    return celError("unsupported_container", "a comprehension reads a list or a map", range);
+}
+function describe(key) {
+    if (typeof key === "string")
+        return JSON.stringify(key);
+    if (isCelUint(key))
+        return `${key.value}`;
+    if (typeof key === "bigint")
+        return `${key}`;
+    return String(key);
+}

package/dist/namespace-resolution.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turning `Alias.fn(x)` into a qualified call.
+ *
+ * `Alias.fn(x)` and `obj.method(x)` are **the same syntax** — a call written on a
+ * receiver — so no parser can tell them apart, and only a set of names that denote
+ * namespaces rather than values can. That set comes from the host, which is why
+ * this is a separate total tree-to-tree pass rather than a parser rule: the parser
+ * has one input and this has two.
+ *
+ * The pass is total — it visits every node and rewrites every receiver call whose
+ * receiver is a bare identifier in the set, wherever it sits. It is also the only
+ * producer of `qcall`, and `cel` and `optional` can never be in the set, because
+ * the standard macros are written on them (`cel.bind(…)`, `optional.of(…)`) and a
+ * namespace would capture those calls instead.
+ *
+ * A resolved tree records the set it was resolved under, so a consumer given a tree
+ * can tell whether it was resolved under the set it is about to check it against —
+ * the alternative is a tree that looks resolved and silently is not.
+ */
+import type { CelNode } from "./syntax-tree.js";
+/** Names that can never be registered as a namespace. */
+export declare const RESERVED_NAMESPACES: readonly string[];
+/** A namespace set a host cannot have: the name is not a name, or is reserved. */
+export declare class CelNamespaceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a namespace set and puts it in a canonical order, so that two sets with
+ * the same names compare equal however the host listed them.
+ */
+export declare function normalizeNamespaces(names: Iterable<string>): readonly string[];
+export declare function namespaceSetsEqual(left: readonly string[], right: readonly string[]): boolean;
+/** Rewrites every call on a name of the set into a `qcall`. Total; shares what it does not change. */
+export declare function resolveNamespaces(root: CelNode, namespaces: readonly string[]): CelNode;
+//# sourceMappingURL=namespace-resolution.d.ts.map

package/dist/namespace-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-resolution.d.ts","sourceRoot":"","sources":["../src/namespace-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAe,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE7D,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAwB,CAAC;AAE1E,kFAAkF;AAClF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAiB9E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE7F;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAsBvF"}

package/dist/namespace-resolution.js

@@ -0,0 +1,160 @@
+/**
+ * Turning `Alias.fn(x)` into a qualified call.
+ *
+ * `Alias.fn(x)` and `obj.method(x)` are **the same syntax** — a call written on a
+ * receiver — so no parser can tell them apart, and only a set of names that denote
+ * namespaces rather than values can. That set comes from the host, which is why
+ * this is a separate total tree-to-tree pass rather than a parser rule: the parser
+ * has one input and this has two.
+ *
+ * The pass is total — it visits every node and rewrites every receiver call whose
+ * receiver is a bare identifier in the set, wherever it sits. It is also the only
+ * producer of `qcall`, and `cel` and `optional` can never be in the set, because
+ * the standard macros are written on them (`cel.bind(…)`, `optional.of(…)`) and a
+ * namespace would capture those calls instead.
+ *
+ * A resolved tree records the set it was resolved under, so a consumer given a tree
+ * can tell whether it was resolved under the set it is about to check it against —
+ * the alternative is a tree that looks resolved and silently is not.
+ */
+import { isIdentifierSpelling, isReservedWord } from "./reserved-words.js";
+/** Names that can never be registered as a namespace. */
+export const RESERVED_NAMESPACES = ["cel", "optional"];
+/** A namespace set a host cannot have: the name is not a name, or is reserved. */
+export class CelNamespaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CelNamespaceError";
+    }
+}
+/**
+ * Validates a namespace set and puts it in a canonical order, so that two sets with
+ * the same names compare equal however the host listed them.
+ */
+export function normalizeNamespaces(names) {
+    const normalized = [];
+    for (const name of names) {
+        if (!isIdentifierSpelling(name)) {
+            throw new CelNamespaceError(`${JSON.stringify(name)} is not spelled as a name, so it names no namespace`);
+        }
+        if (isReservedWord(name)) {
+            throw new CelNamespaceError(`${JSON.stringify(name)} is a reserved word, so it names no namespace`);
+        }
+        if (RESERVED_NAMESPACES.includes(name)) {
+            throw new CelNamespaceError(`${JSON.stringify(name)} is reserved: the standard macros are written on it, and a namespace would capture them`);
+        }
+        if (!normalized.includes(name))
+            normalized.push(name);
+    }
+    return normalized.sort();
+}
+export function namespaceSetsEqual(left, right) {
+    return left.length === right.length && left.every((name, at) => name === right[at]);
+}
+/** Rewrites every call on a name of the set into a `qcall`. Total; shares what it does not change. */
+export function resolveNamespaces(root, namespaces) {
+    // With no namespaces the pass is the identity — nothing can match an empty set — so it
+    // answers without walking. Every site with no module names takes this path, which is why
+    // it is worth stating rather than leaving to the structural sharing below.
+    if (namespaces.length === 0)
+        return root;
+    const resolved = mapChildren(root, (child) => resolveNamespaces(child, namespaces));
+    if (resolved.kind !== "receiverCall")
+        return resolved;
+    const receiver = resolved.receiver;
+    // An absolute name denotes a value the environment declares, never a namespace: a
+    // namespaced call has exactly one spelling, and `.Alias.fn(x)` is not it.
+    if (receiver.kind !== "ident" || receiver.absolute || !namespaces.includes(receiver.name)) {
+        return resolved;
+    }
+    return {
+        kind: "qcall",
+        namespace: receiver.name,
+        namespaceRange: receiver.range,
+        name: resolved.name,
+        nameRange: resolved.nameRange,
+        args: resolved.args,
+        range: resolved.range,
+    };
+}
+/** Rebuilds a node from its mapped children, returning the original when none moved. */
+function mapChildren(node, map) {
+    switch (node.kind) {
+        case "literal":
+        case "ident":
+        case "unparsed":
+            return node;
+        case "list": {
+            let moved = false;
+            const elements = node.elements.map((element) => {
+                const value = map(element.value);
+                if (value === element.value)
+                    return element;
+                moved = true;
+                return { ...element, value };
+            });
+            return moved ? { ...node, elements } : node;
+        }
+        case "map": {
+            let moved = false;
+            const entries = node.entries.map((entry) => {
+                const key = map(entry.key);
+                const value = map(entry.value);
+                if (key === entry.key && value === entry.value)
+                    return entry;
+                moved = true;
+                return { ...entry, key, value };
+            });
+            return moved ? { ...node, entries } : node;
+        }
+        case "select": {
+            const operand = map(node.operand);
+            return operand === node.operand ? node : { ...node, operand };
+        }
+        case "index": {
+            const operand = map(node.operand);
+            const index = map(node.index);
+            return operand === node.operand && index === node.index ? node : { ...node, operand, index };
+        }
+        case "call":
+        case "qcall": {
+            const args = mapList(node.args, map);
+            return args ? { ...node, args } : node;
+        }
+        case "receiverCall": {
+            const receiver = map(node.receiver);
+            const args = mapList(node.args, map);
+            if (receiver === node.receiver && !args)
+                return node;
+            return { ...node, receiver, args: args ?? node.args };
+        }
+        case "unary": {
+            const operand = map(node.operand);
+            return operand === node.operand ? node : { ...node, operand };
+        }
+        case "binary": {
+            const left = map(node.left);
+            const right = map(node.right);
+            return left === node.left && right === node.right ? node : { ...node, left, right };
+        }
+        case "conditional": {
+            const condition = map(node.condition);
+            const whenTrue = map(node.whenTrue);
+            const whenFalse = map(node.whenFalse);
+            return condition === node.condition && whenTrue === node.whenTrue && whenFalse === node.whenFalse
+                ? node
+                : { ...node, condition, whenTrue, whenFalse };
+        }
+    }
+}
+/** The mapped list, or nothing when every element is the one it started as. */
+function mapList(nodes, map) {
+    let moved = false;
+    const mapped = nodes.map((node) => {
+        const next = map(node);
+        if (next !== node)
+            moved = true;
+        return next;
+    });
+    return moved ? mapped : undefined;
+}

package/dist/nominal-type.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Named types a host registers — the one mechanism, with none of the vocabulary.
+ *
+ * A nominal type is a name over a base type, with its own operators, comparisons,
+ * conversions and member functions, and with named **invariant** type parameters. It
+ * is not its base: a value of the base does not stand where the named type is wanted,
+ * and only what the definition declares applies to it. That is what makes a named type
+ * worth having — a slot that wants one refuses a plain value of the base, which is
+ * exactly what an engine typing by wrapper class cannot express.
+ *
+ * Invariance is deliberate: `Holder<string>` and `Holder<int>` are unrelated, so a
+ * type argument that differs is a mistake with its own diagnostic rather than a silent
+ * widening to the base.
+ *
+ * `Self` inside a definition names the type being defined, with its own parameters
+ * applied, so a member can answer its own type without repeating it.
+ */
+import type { CelType, NominalType } from "./cel-type.js";
+import type { NominalResolver } from "./type-expression.js";
+export interface NominalOperatorDeclaration {
+    readonly operator: string;
+    /** Type expressions; `Self` names the type being defined. */
+    readonly parameters: readonly string[];
+    readonly returns: string;
+}
+export interface NominalTypeDefinition {
+    readonly name: string;
+    /** The type expression a value of this type is, underneath. */
+    readonly base: string;
+    /** Invariant type parameter names, each a single capital letter. */
+    readonly parameters?: readonly string[];
+    /** Operators over the type, written with `Self`. */
+    readonly operators?: readonly NominalOperatorDeclaration[];
+    /** Operator symbols to register as `(Self, Self): bool`. */
+    readonly comparisons?: readonly string[];
+    /** Conversion signatures, e.g. `string(Self): string`. */
+    readonly conversions?: readonly string[];
+    /** Member signatures, e.g. `Self.scaled(int): Self`. */
+    readonly members?: readonly string[];
+    readonly description?: string;
+}
+export declare class CelTypeRegistrationError extends Error {
+    constructor(message: string);
+}
+/** A registered nominal type: its definition, its base, and the type `Self` names. */
+export interface RegisteredType {
+    readonly definition: NominalTypeDefinition;
+    readonly base: CelType;
+    readonly parameters: readonly string[];
+    /** The type with its own parameters applied — what `Self` resolves to. */
+    readonly self: NominalType;
+}
+export declare function validateTypeName(name: string): void;
+/**
+ * Builds the registered form of a definition. `resolveNominal` resolves names the
+ * definition's own base or members mention, including itself through `Self`.
+ */
+export declare function buildRegisteredType(definition: NominalTypeDefinition, resolveNominal: NominalResolver): RegisteredType;
+/** The signatures a definition declares, as text, in registration order. */
+export declare function nominalSignatures(definition: NominalTypeDefinition): readonly string[];
+/** The operator declarations a definition implies, its comparisons expanded. */
+export declare function nominalOperators(definition: NominalTypeDefinition): readonly NominalOperatorDeclaration[];
+//# sourceMappingURL=nominal-type.d.ts.map

package/dist/nominal-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nominal-type.d.ts","sourceRoot":"","sources":["../src/nominal-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC3D,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAsBD,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYnD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,qBAAqB,EACjC,cAAc,EAAE,eAAe,GAC9B,cAAc,CA6BhB;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,MAAM,EAAE,CAEtF;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,0BAA0B,EAAE,CAOzG"}