@telorun/cel 0.0.0-stage → 0.107.0

package/dist/value-equality.js

@@ -0,0 +1,196 @@
+/**
+ * Equality and ordering over values — **one comparison, serving both.**
+ *
+ * `<`, `<=`, `>`, `>=`, cross-numeric equality, `in` over a list and a list index all read
+ * the same rule, because two readers of "is this the same value" is how a container and an
+ * operator come to disagree about one expression.
+ *
+ * **Across the numeric types it CONVERTS.** The checker is strict — `1.0 == 1` is a type
+ * error — but `dyn(1.0) == 1` checks, so the runtime is reached with two numeric types in
+ * hand and cel-spec's answer is `true`. Where the double lies outside the integer type's
+ * range the sign decides; otherwise the integer becomes a double and two doubles are
+ * compared, **lossily**, so `dyn(9223372036854775807) < 9223372036854775808.0` is `false`.
+ * That is cel-spec's own rule: its corpus comments the case ("the conversion of the int to
+ * double is lossy") and names the test `not_lt_dyn_int_big_lossy_double`. `int(double)`
+ * refuses a double at or beyond **either** int64 extreme for the same reason.
+ *
+ * An exact comparison is defensible alone and indefensible as a cross-engine contract: a
+ * second engine built on a conformant library would answer the other way on a comparison
+ * that can decide an authorization or a retry bound, silently, at a level no static check
+ * reaches.
+ *
+ * **A map's key identity is NOT this comparison** and does not convert: a map is keyed by
+ * the canonical text of its key, so `{1u: 1.0}[?1.0]` reads the entry and `[?3.1]` names
+ * none.
+ *
+ * Equality across unrelated types is `false`, not an error — two values of different
+ * types are not equal, and asking is not a mistake. Ordering across unrelated types has
+ * no answer, so the caller reports no overload.
+ */
+import { durationNanos } from "./duration-value.js";
+import { mapKeyIdentity } from "./cel-map-value.js";
+import { celTypeNameOf, isCelBytes, isCelDuration, isCelMap, isCelOptional, isCelRecord, isCelTimestamp, isCelTypeValue, isCelUint, } from "./cel-value.js";
+import { timestampNanos } from "./timestamp-value.js";
+/** The int64 and uint64 extremes as doubles. Each reads as the nearest double there is. */
+const MIN_INT_AS_DOUBLE = -9223372036854775808;
+const MAX_INT_AS_DOUBLE = 9223372036854775807;
+const MAX_UINT_AS_DOUBLE = 18446744073709551615;
+/**
+ * Comparing an integer against a double, cel-spec's way: outside the integer type's range
+ * the sign decides, inside it both sides are doubles. Nothing for NaN, which orders with
+ * nothing including itself.
+ */
+function compareIntegerDouble(left, unsigned, right) {
+    if (Number.isNaN(right))
+        return undefined;
+    if (right < (unsigned ? 0 : MIN_INT_AS_DOUBLE))
+        return 1;
+    if (right > (unsigned ? MAX_UINT_AS_DOUBLE : MAX_INT_AS_DOUBLE))
+        return -1;
+    const converted = Number(left);
+    return converted < right ? -1 : converted > right ? 1 : 0;
+}
+function compareNumbers(left, right) {
+    if (Number.isNaN(left) || Number.isNaN(right))
+        return undefined;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function compareBigints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** The numeric magnitude of a value, where it has one, and which range it belongs to. */
+function numeric(value) {
+    if (typeof value === "bigint")
+        return { integer: value, unsigned: false };
+    if (typeof value === "number")
+        return { double: value };
+    if (isCelUint(value))
+        return { integer: value.value, unsigned: true };
+    return undefined;
+}
+/** Whether two numeric values compare, and how. Nothing where one is NaN. */
+function compareNumeric(left, right) {
+    const a = numeric(left);
+    const b = numeric(right);
+    if (!a || !b)
+        return undefined;
+    if ("integer" in a && "integer" in b) {
+        // An int and a uint are both exact integers, so one comparison serves both.
+        return compareBigints(a.integer, b.integer);
+    }
+    if ("integer" in a) {
+        return compareIntegerDouble(a.integer, a.unsigned, b.double);
+    }
+    if ("integer" in b) {
+        const compared = compareIntegerDouble(b.integer, b.unsigned, a.double);
+        return compared === undefined ? undefined : -compared;
+    }
+    return compareNumbers(a.double, b.double);
+}
+function compareBytes(left, right) {
+    const shared = Math.min(left.length, right.length);
+    for (let at = 0; at < shared; at += 1) {
+        if (left[at] !== right[at])
+            return left[at] < right[at] ? -1 : 1;
+    }
+    return left.length === right.length ? 0 : left.length < right.length ? -1 : 1;
+}
+/**
+ * How two values order: `-1`, `0`, `1`, or nothing when they do not order at all —
+ * unrelated types, or a NaN, which orders with nothing including itself.
+ */
+export function celCompare(left, right) {
+    if (numeric(left) && numeric(right))
+        return compareNumeric(left, right);
+    if (typeof left === "string" && typeof right === "string") {
+        return left < right ? -1 : left > right ? 1 : 0;
+    }
+    if (typeof left === "boolean" && typeof right === "boolean") {
+        return left === right ? 0 : left ? 1 : -1;
+    }
+    if (isCelBytes(left) && isCelBytes(right))
+        return compareBytes(left, right);
+    if (isCelTimestamp(left) && isCelTimestamp(right)) {
+        return compareBigints(timestampNanos(left), timestampNanos(right));
+    }
+    if (isCelDuration(left) && isCelDuration(right)) {
+        return compareBigints(durationNanos(left), durationNanos(right));
+    }
+    return undefined;
+}
+/** CEL equality: by value, across the numeric types, and `false` across unrelated ones. */
+export function celEqual(left, right) {
+    // One identical primitive is equal to itself, and the two edges agree: `-0 === 0` and CEL
+    // says they are equal, `NaN !== NaN` and CEL says they are not — so the slow path below
+    // answers NaN correctly after this check declines it.
+    if (left === right && typeof left !== "object")
+        return true;
+    if (numeric(left) && numeric(right))
+        return compareNumeric(left, right) === 0;
+    if (left === null || right === null)
+        return left === right;
+    const leftType = celTypeNameOf(left);
+    if (leftType !== celTypeNameOf(right))
+        return false;
+    switch (leftType) {
+        case "bool":
+        case "string":
+            return left === right;
+        case "bytes":
+            return compareBytes(left, right) === 0;
+        case "google.protobuf.Timestamp":
+            return timestampNanos(left) === timestampNanos(right);
+        case "google.protobuf.Duration":
+            return durationNanos(left) === durationNanos(right);
+        case "type":
+            return isCelTypeValue(left) && isCelTypeValue(right) && left.name === right.name;
+        case "list":
+            return equalLists(left, right);
+        case "map":
+            return equalMaps(left, right);
+        case "optional":
+            return equalOptionals(left, right);
+        default:
+            // A host's own named type: equal when the host's operator says so, which it
+            // registers itself. With none registered, identity is all this engine knows.
+            return left === right;
+    }
+}
+function equalLists(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((value, at) => celEqual(value, right[at]));
+}
+/** Every key of a map, as the pairs equality walks. */
+function mapPairs(value) {
+    if (isCelMap(value)) {
+        return new Map([...value.entries].map(([identity, entry]) => [identity, entry.value]));
+    }
+    if (isCelRecord(value)) {
+        const pairs = new Map();
+        for (const key of Object.keys(value))
+            pairs.set(mapKeyIdentity(key), value[key]);
+        return pairs;
+    }
+    return undefined;
+}
+function equalMaps(left, right) {
+    const a = mapPairs(left);
+    const b = mapPairs(right);
+    if (!a || !b || a.size !== b.size)
+        return false;
+    for (const [identity, value] of a) {
+        if (!b.has(identity))
+            return false;
+        if (!celEqual(value, b.get(identity)))
+            return false;
+    }
+    return true;
+}
+function equalOptionals(left, right) {
+    if (!isCelOptional(left) || !isCelOptional(right))
+        return false;
+    if (left.present !== right.present)
+        return false;
+    return !left.present || celEqual(left.held, right.held);
+}

package/dist/value-text.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Text: how a value is written as a string, and how text becomes bytes.
+ *
+ * `string()` is the one conversion a consumer renders a value through — an interpolated
+ * hole is defined as the CEL join of `string(<hole>)` — so each form here is the value's
+ * single written form, the same one the plain encoding uses: RFC 3339 for an instant,
+ * seconds with an `s` for a duration, UTF-8 text for bytes.
+ */
+import { type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+/** The UTF-8 bytes of text. */
+export declare function textToBytes(text: string): Uint8Array;
+/**
+ * The text bytes hold. Bytes that are not UTF-8 are a conversion error rather than text
+ * with a replacement character in it: a replacement character is a value the author
+ * never wrote, and it would read back as different bytes.
+ */
+export declare function bytesToText(bytes: Uint8Array, range?: SourceRange): string | CelError;
+/**
+ * A double as text. The shortest digits that read back as the same double, which is the
+ * host's own shortest-round-trip form; the non-finite doubles are named as cel-spec
+ * writes them.
+ */
+export declare function doubleText(value: number): string;
+//# sourceMappingURL=value-text.d.ts.map

package/dist/value-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-text.d.ts","sourceRoot":"","sources":["../src/value-text.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKpD,+BAA+B;AAC/B,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,QAAQ,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD"}

package/dist/value-text.js

@@ -0,0 +1,44 @@
+/**
+ * Text: how a value is written as a string, and how text becomes bytes.
+ *
+ * `string()` is the one conversion a consumer renders a value through — an interpolated
+ * hole is defined as the CEL join of `string(<hole>)` — so each form here is the value's
+ * single written form, the same one the plain encoding uses: RFC 3339 for an instant,
+ * seconds with an `s` for a duration, UTF-8 text for bytes.
+ */
+import { celError } from "./cel-value.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/** The UTF-8 bytes of text. */
+export function textToBytes(text) {
+    return encoder.encode(text);
+}
+/**
+ * The text bytes hold. Bytes that are not UTF-8 are a conversion error rather than text
+ * with a replacement character in it: a replacement character is a value the author
+ * never wrote, and it would read back as different bytes.
+ */
+export function bytesToText(bytes, range) {
+    try {
+        return decoder.decode(bytes);
+    }
+    catch {
+        return celError("invalid_conversion", "the bytes are not UTF-8 text", range);
+    }
+}
+/**
+ * A double as text. The shortest digits that read back as the same double, which is the
+ * host's own shortest-round-trip form; the non-finite doubles are named as cel-spec
+ * writes them.
+ */
+export function doubleText(value) {
+    if (Number.isNaN(value))
+        return "NaN";
+    if (value === Number.POSITIVE_INFINITY)
+        return "+Inf";
+    if (value === Number.NEGATIVE_INFINITY)
+        return "-Inf";
+    if (value === 0 && Object.is(value, -0))
+        return "-0";
+    return String(value);
+}

package/dist/zoned-calendar.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The calendar in a time zone: an instant's wall-clock fields, and the instant a wall
+ * clock names.
+ *
+ * An instant is only a date once a zone is chosen, so every calendar function of the
+ * function catalog reads its fields through here. The zone's RULES are the host's data
+ * (`Intl.DateTimeFormat`, ECMA-402, present in a browser as in Node), never this
+ * engine's: what is written here is only how those rules are applied, which is the half
+ * a second engine has to reproduce.
+ *
+ * It is separate from `timestamp-value.ts` on purpose. That file is the language's own
+ * zone reading — cel-spec's getters, which also accept a fixed `HH:MM` offset and word
+ * their refusal as the language does. This one is the catalog's: it accepts an IANA name
+ * alone, it is millisecond-granular because the functions built on it render
+ * milliseconds, and it answers a gap or a repeated wall clock the way a calendar
+ * library does. Folding the two would make one of the two behaviours wrong.
+ */
+/** A wall clock, to the second: what a zone makes of an instant. */
+export interface CivilTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+/**
+ * Whether the host knows the zone. The catalog's refusal is worded by its caller, so
+ * this answers only yes or no — left to `Intl` the failure is a `RangeError` naming
+ * neither the function nor what was wrong with the argument.
+ */
+export declare function knownTimeZone(zone: string): boolean;
+/** The wall clock an instant reads as in a zone. */
+export declare function civilTimeIn(instant: number, zone: string): CivilTime;
+/**
+ * The instant whose wall clock in `zone` is these fields.
+ *
+ * The offset depends on the instant being solved for, so this takes the offset at the
+ * UTC reading, corrects, and then **checks** by reading the result back. That check is
+ * the whole point: a plain fixpoint settles on an instant whose wall clock is not the one
+ * asked for whenever the requested time does not exist, and it settles BACKWARDS — which
+ * silently moves the calendar day, the one thing `addMonths` and `startOfMonth` exist to
+ * control. Chile jumps 00:00 to 01:00 on 2026-09-06 and Cuba on 2026-03-08, so "the 6th
+ * at midnight" there is not a time; a fixpoint answered "the 5th at 23:00".
+ *
+ * Resolution follows Java's `ZonedDateTime` and Temporal's `compatible`: a wall clock
+ * that exists twice (a fall-back) takes the EARLIER instant, and one that does not exist
+ * (a spring-forward gap) shifts FORWARD out of the gap, which keeps the requested day.
+ */
+export declare function instantOfCivilTime(fields: CivilTime, zone: string): number;
+/** `Date.UTC` maps years 0-99 to 1900-1999, so the year is set explicitly. */
+export declare function daysInMonth(year: number, month: number): number;
+/** The calendar date (`YYYY-MM-DD`) an instant reads as in a zone. */
+export declare function dateTextIn(instant: number, zone: string): string;
+/**
+ * An instant as ISO-8601 in a zone, with milliseconds: UTC as `…Z`, else the zone's own
+ * offset (`2026-06-06T18:30:00.000-05:00`). The offset is derived arithmetically from
+ * standard `Intl` fields, so nothing here needs a newer ECMA-402 surface.
+ */
+export declare function isoTextIn(instant: number, zone: string): string;
+//# sourceMappingURL=zoned-calendar.d.ts.map

package/dist/zoned-calendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoned-calendar.d.ts","sourceRoot":"","sources":["../src/zoned-calendar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOnD;AA0BD,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAUpE;AAsBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAqB1E;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/D;AAMD,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB/D"}

package/dist/zoned-calendar.js

@@ -0,0 +1,143 @@
+/**
+ * The calendar in a time zone: an instant's wall-clock fields, and the instant a wall
+ * clock names.
+ *
+ * An instant is only a date once a zone is chosen, so every calendar function of the
+ * function catalog reads its fields through here. The zone's RULES are the host's data
+ * (`Intl.DateTimeFormat`, ECMA-402, present in a browser as in Node), never this
+ * engine's: what is written here is only how those rules are applied, which is the half
+ * a second engine has to reproduce.
+ *
+ * It is separate from `timestamp-value.ts` on purpose. That file is the language's own
+ * zone reading — cel-spec's getters, which also accept a fixed `HH:MM` offset and word
+ * their refusal as the language does. This one is the catalog's: it accepts an IANA name
+ * alone, it is millisecond-granular because the functions built on it render
+ * milliseconds, and it answers a gap or a repeated wall clock the way a calendar
+ * library does. Folding the two would make one of the two behaviours wrong.
+ */
+/**
+ * Whether the host knows the zone. The catalog's refusal is worded by its caller, so
+ * this answers only yes or no — left to `Intl` the failure is a `RangeError` naming
+ * neither the function nor what was wrong with the argument.
+ */
+export function knownTimeZone(zone) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const FIELD_OPTIONS = {
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+};
+function zoneParts(instant, zone, options) {
+    const parts = {};
+    for (const part of new Intl.DateTimeFormat("en-US", { timeZone: zone, ...options }).formatToParts(new Date(instant))) {
+        parts[part.type] = part.value;
+    }
+    return parts;
+}
+/** The wall clock an instant reads as in a zone. */
+export function civilTimeIn(instant, zone) {
+    const parts = zoneParts(instant, zone, FIELD_OPTIONS);
+    return {
+        year: +parts.year,
+        month: +parts.month,
+        day: +parts.day,
+        hour: +parts.hour,
+        minute: +parts.minute,
+        second: +parts.second,
+    };
+}
+/** The zone's offset at an instant, in milliseconds: its wall clock read as UTC, minus it. */
+function offsetAt(instant, zone) {
+    const fields = civilTimeIn(instant, zone);
+    return (Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second) -
+        instant);
+}
+function sameWallClock(left, right) {
+    return (left.year === right.year &&
+        left.month === right.month &&
+        left.day === right.day &&
+        left.hour === right.hour &&
+        left.minute === right.minute &&
+        left.second === right.second);
+}
+/**
+ * The instant whose wall clock in `zone` is these fields.
+ *
+ * The offset depends on the instant being solved for, so this takes the offset at the
+ * UTC reading, corrects, and then **checks** by reading the result back. That check is
+ * the whole point: a plain fixpoint settles on an instant whose wall clock is not the one
+ * asked for whenever the requested time does not exist, and it settles BACKWARDS — which
+ * silently moves the calendar day, the one thing `addMonths` and `startOfMonth` exist to
+ * control. Chile jumps 00:00 to 01:00 on 2026-09-06 and Cuba on 2026-03-08, so "the 6th
+ * at midnight" there is not a time; a fixpoint answered "the 5th at 23:00".
+ *
+ * Resolution follows Java's `ZonedDateTime` and Temporal's `compatible`: a wall clock
+ * that exists twice (a fall-back) takes the EARLIER instant, and one that does not exist
+ * (a spring-forward gap) shifts FORWARD out of the gap, which keeps the requested day.
+ */
+export function instantOfCivilTime(fields, zone) {
+    const asUtc = Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second);
+    const offsetA = offsetAt(asUtc, zone);
+    const candidateA = asUtc - offsetA;
+    const offsetB = offsetAt(candidateA, zone);
+    if (offsetA === offsetB)
+        return candidateA;
+    const candidateB = asUtc - offsetB;
+    const aHolds = sameWallClock(civilTimeIn(candidateA, zone), fields);
+    const bHolds = sameWallClock(civilTimeIn(candidateB, zone), fields);
+    if (aHolds && bHolds)
+        return Math.min(candidateA, candidateB);
+    if (aHolds)
+        return candidateA;
+    if (bHolds)
+        return candidateB;
+    return Math.max(candidateA, candidateB);
+}
+/** `Date.UTC` maps years 0-99 to 1900-1999, so the year is set explicitly. */
+export function daysInMonth(year, month) {
+    const date = new Date(Date.UTC(2000, month, 0));
+    date.setUTCFullYear(year, month, 0);
+    return date.getUTCDate();
+}
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+/** The calendar date (`YYYY-MM-DD`) an instant reads as in a zone. */
+export function dateTextIn(instant, zone) {
+    if (zone === "UTC" || zone === "Z")
+        return new Date(instant).toISOString().slice(0, 10);
+    const parts = zoneParts(instant, zone, { year: "numeric", month: "2-digit", day: "2-digit" });
+    return `${parts.year}-${parts.month}-${parts.day}`;
+}
+/**
+ * An instant as ISO-8601 in a zone, with milliseconds: UTC as `…Z`, else the zone's own
+ * offset (`2026-06-06T18:30:00.000-05:00`). The offset is derived arithmetically from
+ * standard `Intl` fields, so nothing here needs a newer ECMA-402 surface.
+ */
+export function isoTextIn(instant, zone) {
+    if (zone === "UTC" || zone === "Z")
+        return new Date(instant).toISOString();
+    const fields = civilTimeIn(instant, zone);
+    // Sub-second is zone-independent; read it off the instant directly.
+    const milliseconds = pad(((instant % 1000) + 1000) % 1000, 3);
+    const minutes = Math.round((Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second) -
+        instant) /
+        60000);
+    const offset = minutes === 0
+        ? "Z"
+        : `${minutes > 0 ? "+" : "-"}${pad(Math.floor(Math.abs(minutes) / 60), 2)}:${pad(Math.abs(minutes) % 60, 2)}`;
+    const date = `${pad(fields.year, 4)}-${pad(fields.month, 2)}-${pad(fields.day, 2)}`;
+    const time = `${pad(fields.hour, 2)}:${pad(fields.minute, 2)}:${pad(fields.second, 2)}`;
+    return `${date}T${time}.${milliseconds}${offset}`;
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@telorun/cel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.107.0",
+  "description": "The Common Expression Language for Telo: read, type-check and evaluate an expression, hold it as a tree, write it back.",
+  "keywords": [
+    "telo",
+    "cel",
+    "expression",
+    "parser"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "cel/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "src/**"
+  ],
+  "dependencies": {
+    "d3-format": "3.1.2",
+    "re2js": "2.8.3",
+    "uuid": "14.0.1"
+  },
+  "devDependencies": {
+    "@types/d3-format": "^3.0.4",
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:conformance": "vitest run --config vitest.conformance.config.ts",
+    "check:types": "tsc -p tsconfig.json --noEmit",
+    "check:browser-safe": "node scripts/check-browser-safe.mjs",
+    "check:signatures": "pnpm run build && node scripts/check-signatures.mjs"
+  }
 }

package/src/activation.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 function activationHolds(activation: CelActivation, name: string): boolean {
+  return Object.prototype.hasOwnProperty.call(activation, name);
+}