@telorun/cel 0.0.0-stage → 0.107.0

package/dist/comprehension-runtime.js

@@ -0,0 +1,137 @@
+/**
+ * What a comprehension macro **does**, as a function of its range and its body.
+ *
+ * The macros are lowered by each backend — there is no comprehension node in the tree,
+ * because expanding one at read time would make the source unwritable from the tree —
+ * but what the lowering *means* lives here, once. The closure backend passes a closure
+ * as the body and the emitter will pass an emitted function, and both get the same
+ * answers, including the error rules.
+ *
+ * **An error does not win over a decided answer**, with the one exception named below: `all`
+ * is `false` as soon as one element is false even if another errors, and `exists` is `true` as
+ * soon as one is true. That is the same rule `&&` and `||` follow, and it is what makes a
+ * comprehension over partly-unreadable data usable at all.
+ *
+ * **An element entering a body is a door a host value comes through**, and it is checked for a
+ * thenable here — in the one place a comprehension's meaning lives, so both backends inherit it
+ * rather than each remembering to. It is not the leak it looks like: `xs.all(e, true)` over a
+ * host list holding a promise used to answer **`true`**, having decided something about a value
+ * it never touched, which is the worse half of the failure class. The cost is one `typeof` per
+ * element, the same check the member read already makes, on a loop that already calls a closure
+ * per element.
+ *
+ * **That refusal is TERMINAL, and it is the one error here that does not short-circuit.** It is
+ * checked where the element is BOUND, before the body runs, and it ends the comprehension
+ * whatever a later element would have decided — so `xs.all(e, false)` and `xs.exists(e, true)`
+ * refuse rather than answering `false` and `true` off the one element that is readable. The
+ * distinction is what the error is ABOUT: `no_such_key` is a fact about one datum, so a decided
+ * answer may legitimately outrank it, while a value that must be awaited says the host handed
+ * this engine something it cannot evaluate at all. Carrying that past a convenient element makes
+ * the answer depend on how many elements happen to be readable and in what order — and the rule
+ * is subtle enough that two readers in a row took the discardable refusal for a leak instead.
+ */
+import { asyncValueRefused, celError, isCelError } from "./cel-value.js";
+function notBool(value, range) {
+    return celError("no_matching_overload", `a comprehension's test must answer a bool, and it answered ${typeof value}`, range);
+}
+/**
+ * Whether an element entering a body is one that must be awaited.
+ *
+ * The `typeof` is inlined here rather than left to the call, because this runs once per element
+ * on the engine's hottest loop and only an OBJECT can be a thenable. Measured on a
+ * 100k-element `map` over integers — a body that does almost nothing, so the check is as
+ * visible as it ever gets: calling unconditionally cost about 4 ms, and with the `typeof`
+ * guarding the call the difference sits at this machine's noise floor.
+ */
+function awaited(element, range) {
+    if (typeof element !== "object" || element === null)
+        return undefined;
+    return asyncValueRefused(element, range);
+}
+/** A predicate's answer for one element: `true`, `false`, or the error it is. */
+function test(body, element, range) {
+    const answered = body(element);
+    if (isCelError(answered))
+        return answered;
+    if (typeof answered !== "boolean")
+        return notBool(answered, range);
+    return answered;
+}
+export function celAll(elements, body, range) {
+    let failure;
+    for (const element of elements) {
+        const refused = awaited(element, range);
+        if (refused)
+            return refused;
+        const answered = test(body, element, range);
+        if (answered === false)
+            return false;
+        if (answered !== true && !failure)
+            failure = answered;
+    }
+    return failure ?? true;
+}
+export function celExists(elements, body, range) {
+    let failure;
+    for (const element of elements) {
+        const refused = awaited(element, range);
+        if (refused)
+            return refused;
+        const answered = test(body, element, range);
+        if (answered === true)
+            return true;
+        if (answered !== false && !failure)
+            failure = answered;
+    }
+    return failure ?? false;
+}
+/** Exactly one element satisfies the test. An error anywhere leaves no count to trust. */
+export function celExistsOne(elements, body, range) {
+    let found = 0;
+    for (const element of elements) {
+        const refused = awaited(element, range);
+        if (refused)
+            return refused;
+        const answered = test(body, element, range);
+        if (isCelError(answered))
+            return answered;
+        if (answered)
+            found += 1;
+    }
+    return found === 1;
+}
+export function celFilter(elements, body, range) {
+    const kept = [];
+    for (const element of elements) {
+        const refused = awaited(element, range);
+        if (refused)
+            return refused;
+        const answered = test(body, element, range);
+        if (isCelError(answered))
+            return answered;
+        if (answered)
+            kept.push(element);
+    }
+    return kept;
+}
+/** `map` in both arities: with a filter, an element the filter drops is not transformed. */
+export function celMapComprehension(elements, transform, filter, range) {
+    const out = [];
+    for (const element of elements) {
+        const refused = awaited(element, range);
+        if (refused)
+            return refused;
+        if (filter) {
+            const answered = test(filter, element, range);
+            if (isCelError(answered))
+                return answered;
+            if (!answered)
+                continue;
+        }
+        const value = transform(element);
+        if (isCelError(value))
+            return value;
+        out.push(value);
+    }
+    return out;
+}

package/dist/declared-chain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Splitting a dotted chain over the names a host DECLARED — once, for both halves.
+ *
+ * A host may declare `a.b.c`, or `a.b` holding a map, or both. `a.b.c` then reads the
+ * variable of that name where it is declared and the map's entry where only `a.b` is, so the
+ * host's own naming decides rather than the shape of the expression: the **longest declared
+ * prefix wins**.
+ *
+ * The checker and the backend ask the same question of the same declarations, so they ask it
+ * here. Two readers would be two answers to "which name is this chain", and the pair that
+ * disagrees is the worst kind: `telo check` types one name while evaluation reads another, and
+ * nothing says so. Splitting at compile time also means a declared chain costs **one**
+ * activation read at evaluation rather than a search over its prefixes.
+ *
+ * A chain **no prefix of which** is declared — the root included — is left alone: there is
+ * nothing to split it on, and the checker has no opinion about it either. The backend then
+ * searches the activation at evaluation, which is what every conformance row binding a dotted
+ * key relies on. Where any prefix IS declared the search never runs, so a key the host did not
+ * declare can never win over a name it did.
+ */
+/** Where a chain splits: the declared name, and the members read off its value. */
+export interface DeclaredChain {
+    readonly name: string;
+    readonly rest: readonly string[];
+}
+/**
+ * The longest declared prefix of a chain, or nothing when no declaration covers one.
+ *
+ * **The root counts as a prefix**, and leaving it out was the disagreement this function
+ * exists to prevent: with a chain whose root alone is declared treated as undeclared, the
+ * backend fell into the activation prefix search, and an activation holding both `a` and the
+ * key `"a.b"` answered the undeclared key where the checker had typed the declared name.
+ */
+export declare function splitDeclaredChain(segments: readonly string[], declared: (name: string) => boolean): DeclaredChain | undefined;
+//# sourceMappingURL=declared-chain.d.ts.map

package/dist/declared-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-chain.d.ts","sourceRoot":"","sources":["../src/declared-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAClC,aAAa,GAAG,SAAS,CAM3B"}

package/dist/declared-chain.js

@@ -0,0 +1,36 @@
+/**
+ * Splitting a dotted chain over the names a host DECLARED — once, for both halves.
+ *
+ * A host may declare `a.b.c`, or `a.b` holding a map, or both. `a.b.c` then reads the
+ * variable of that name where it is declared and the map's entry where only `a.b` is, so the
+ * host's own naming decides rather than the shape of the expression: the **longest declared
+ * prefix wins**.
+ *
+ * The checker and the backend ask the same question of the same declarations, so they ask it
+ * here. Two readers would be two answers to "which name is this chain", and the pair that
+ * disagrees is the worst kind: `telo check` types one name while evaluation reads another, and
+ * nothing says so. Splitting at compile time also means a declared chain costs **one**
+ * activation read at evaluation rather than a search over its prefixes.
+ *
+ * A chain **no prefix of which** is declared — the root included — is left alone: there is
+ * nothing to split it on, and the checker has no opinion about it either. The backend then
+ * searches the activation at evaluation, which is what every conformance row binding a dotted
+ * key relies on. Where any prefix IS declared the search never runs, so a key the host did not
+ * declare can never win over a name it did.
+ */
+/**
+ * The longest declared prefix of a chain, or nothing when no declaration covers one.
+ *
+ * **The root counts as a prefix**, and leaving it out was the disagreement this function
+ * exists to prevent: with a chain whose root alone is declared treated as undeclared, the
+ * backend fell into the activation prefix search, and an activation holding both `a` and the
+ * key `"a.b"` answered the undeclared key where the checker had typed the declared name.
+ */
+export function splitDeclaredChain(segments, declared) {
+    for (let length = segments.length; length >= 1; length -= 1) {
+        const name = segments.slice(0, length).join(".");
+        if (declared(name))
+            return { name, rest: segments.slice(length) };
+    }
+    return undefined;
+}

package/dist/duration-value.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Durations: reading one, writing one, and the fields of one.
+ *
+ * **CEL's duration is the signed 64-bit range of its total NANOSECONDS** —
+ * `-9223372036.854775808s … 9223372036.854775807s`, roughly ±292 years. That is cel-spec's
+ * own rule, stated under *Overflow* in its language definition ("Duration values are
+ * limited to a single int64 value, or roughly +-290 years"), and all six of the vectors'
+ * `timestamps/duration_range` rows read it: each uses an operand of 200,000,000,000s or
+ * 320,000,000,000s and each expects `duration out of range`.
+ *
+ * **It is a subrange of the typed frame's, deliberately.** The frame carries protobuf's
+ * `google.protobuf.Duration` range — ±315,576,000,000s, ±10,000 years — because a duration
+ * arriving from a transport, a journal or a controller must always be representable, and
+ * narrowing the frame to CEL's range would make such a value unwritable. So CEL ⊂ frame:
+ * `duration('200000000000s')` is a value the frame carries and CEL cannot construct, which
+ * is the correct answer rather than a cost. Nothing about the frame changes here.
+ *
+ * The range is an invariant, not a storage format: a duration is still seconds and
+ * nanoseconds of the same sign, with `|nanos| < 1e9`, and nanosecond-precise. A computation
+ * that leaves the range is an error, never a value outside it.
+ *
+ * It is written as seconds with an `s` suffix (`1000000s`, `-1.5s`), which is cel-spec's
+ * own spelling, and the one plain encoding a duration has wherever it is written down.
+ */
+import { type CelDuration, type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+/** The widest and narrowest total a duration holds, in nanoseconds: int64. */
+export declare const MAX_DURATION_NANOS = 9223372036854775807n;
+export declare const MIN_DURATION_NANOS = -9223372036854775808n;
+/** A duration from a total in nanoseconds, or the range error. */
+export declare function celDurationFromNanos(total: bigint, range?: SourceRange): CelDuration | CelError;
+/**
+ * The error a duration **this engine did not build** is outside CEL's range: one from a
+ * host, which the frame's wider range admits. Checked where such a duration is used, not
+ * where it arrives, so a value merely passing through is not judged.
+ */
+export declare function durationOutOfRange(value: CelDuration, range?: SourceRange): CelError | undefined;
+/** The duration's total nanoseconds — what arithmetic and ordering compare. */
+export declare function durationNanos(value: CelDuration): bigint;
+/**
+ * A duration from CEL's own text: a sign, then one or more number-and-unit parts over
+ * `ns`, `us`, `ms`, `s`, `m` and `h` (`1h30m`, `1.5s`, `-10m`).
+ */
+export declare function parseDuration(text: string, range?: SourceRange): CelDuration | CelError;
+/** Seconds with an `s` suffix, the fraction trimmed to what it carries. */
+export declare function formatDuration(value: CelDuration): string;
+/** Which field of a duration a getter answers. */
+export type DurationField = "getHours" | "getMinutes" | "getSeconds" | "getMilliseconds";
+/**
+ * A field of a duration. `getHours`, `getMinutes` and `getSeconds` answer the **whole span**
+ * in that unit, truncated toward zero; `getMilliseconds` answers the **component** — the
+ * milliseconds inside the second, so `duration('123.321456789s').getMilliseconds()` is 321
+ * and not 123,321.
+ *
+ * That split is cel-spec's, and it is also the only reading under which the engine does not
+ * contradict itself: a timestamp's `getMilliseconds()` has always answered the component.
+ */
+export declare function durationField(value: CelDuration, field: DurationField): bigint;
+//# sourceMappingURL=duration-value.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"duration-value.d.ts","sourceRoot":"","sources":["../src/duration-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAA4B,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,uBAA6B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,wBAA8B,CAAC;AAI9D,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,QAAQ,CAS/F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAIhG;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAExD;AAeD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,QAAQ,CA4BvF;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAQzD;AAED,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAEzF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAY9E"}

package/dist/duration-value.js

@@ -0,0 +1,135 @@
+/**
+ * Durations: reading one, writing one, and the fields of one.
+ *
+ * **CEL's duration is the signed 64-bit range of its total NANOSECONDS** —
+ * `-9223372036.854775808s … 9223372036.854775807s`, roughly ±292 years. That is cel-spec's
+ * own rule, stated under *Overflow* in its language definition ("Duration values are
+ * limited to a single int64 value, or roughly +-290 years"), and all six of the vectors'
+ * `timestamps/duration_range` rows read it: each uses an operand of 200,000,000,000s or
+ * 320,000,000,000s and each expects `duration out of range`.
+ *
+ * **It is a subrange of the typed frame's, deliberately.** The frame carries protobuf's
+ * `google.protobuf.Duration` range — ±315,576,000,000s, ±10,000 years — because a duration
+ * arriving from a transport, a journal or a controller must always be representable, and
+ * narrowing the frame to CEL's range would make such a value unwritable. So CEL ⊂ frame:
+ * `duration('200000000000s')` is a value the frame carries and CEL cannot construct, which
+ * is the correct answer rather than a cost. Nothing about the frame changes here.
+ *
+ * The range is an invariant, not a storage format: a duration is still seconds and
+ * nanoseconds of the same sign, with `|nanos| < 1e9`, and nanosecond-precise. A computation
+ * that leaves the range is an error, never a value outside it.
+ *
+ * It is written as seconds with an `s` suffix (`1000000s`, `-1.5s`), which is cel-spec's
+ * own spelling, and the one plain encoding a duration has wherever it is written down.
+ */
+import { celError, CEL_VALUE_TYPE } from "./cel-value.js";
+/** The widest and narrowest total a duration holds, in nanoseconds: int64. */
+export const MAX_DURATION_NANOS = 9223372036854775807n;
+export const MIN_DURATION_NANOS = -9223372036854775808n;
+const NANOS_PER_SECOND = 1000000000n;
+/** A duration from a total in nanoseconds, or the range error. */
+export function celDurationFromNanos(total, range) {
+    if (total > MAX_DURATION_NANOS || total < MIN_DURATION_NANOS) {
+        return celError("invalid_conversion", "duration out of range", range);
+    }
+    return {
+        [CEL_VALUE_TYPE]: "google.protobuf.Duration",
+        seconds: total / NANOS_PER_SECOND,
+        nanos: Number(total % NANOS_PER_SECOND),
+    };
+}
+/**
+ * The error a duration **this engine did not build** is outside CEL's range: one from a
+ * host, which the frame's wider range admits. Checked where such a duration is used, not
+ * where it arrives, so a value merely passing through is not judged.
+ */
+export function durationOutOfRange(value, range) {
+    const total = durationNanos(value);
+    if (total <= MAX_DURATION_NANOS && total >= MIN_DURATION_NANOS)
+        return undefined;
+    return celError("invalid_conversion", "duration out of range", range);
+}
+/** The duration's total nanoseconds — what arithmetic and ordering compare. */
+export function durationNanos(value) {
+    return value.seconds * NANOS_PER_SECOND + BigInt(value.nanos);
+}
+const UNIT_NANOS = {
+    ns: 1n,
+    us: 1000n,
+    "µs": 1000n,
+    "μs": 1000n,
+    ms: 1000000n,
+    s: 1000000000n,
+    m: 60000000000n,
+    h: 3600000000000n,
+};
+const PART = /([0-9]*)(?:\.([0-9]*))?(ns|us|µs|μs|ms|s|m|h)/g;
+/**
+ * A duration from CEL's own text: a sign, then one or more number-and-unit parts over
+ * `ns`, `us`, `ms`, `s`, `m` and `h` (`1h30m`, `1.5s`, `-10m`).
+ */
+export function parseDuration(text, range) {
+    const refuse = () => celError("invalid_conversion", `${JSON.stringify(text)} is not a duration`, range);
+    let body = text;
+    let negative = false;
+    if (body.startsWith("+") || body.startsWith("-")) {
+        negative = body.startsWith("-");
+        body = body.slice(1);
+    }
+    if (body === "0")
+        return celDurationFromNanos(0n, range);
+    if (body === "")
+        return refuse();
+    PART.lastIndex = 0;
+    let total = 0n;
+    let at = 0;
+    for (let found = PART.exec(body); found; found = PART.exec(body)) {
+        if (found.index !== at)
+            return refuse();
+        const [whole, digits, fraction, unit] = found;
+        if (!digits && !fraction)
+            return refuse();
+        const scale = UNIT_NANOS[unit];
+        total += BigInt(digits || "0") * scale;
+        if (fraction) {
+            const padded = `${fraction}000000000`.slice(0, 9);
+            total += (BigInt(padded) * scale) / NANOS_PER_SECOND;
+        }
+        at += whole.length;
+    }
+    if (at !== body.length)
+        return refuse();
+    return celDurationFromNanos(negative ? -total : total, range);
+}
+/** Seconds with an `s` suffix, the fraction trimmed to what it carries. */
+export function formatDuration(value) {
+    const total = durationNanos(value);
+    const negative = total < 0n;
+    const magnitude = negative ? -total : total;
+    const seconds = magnitude / NANOS_PER_SECOND;
+    const nanos = magnitude % NANOS_PER_SECOND;
+    const fraction = nanos === 0n ? "" : `.${String(nanos).padStart(9, "0").replace(/0+$/, "")}`;
+    return `${negative ? "-" : ""}${seconds}${fraction}s`;
+}
+/**
+ * A field of a duration. `getHours`, `getMinutes` and `getSeconds` answer the **whole span**
+ * in that unit, truncated toward zero; `getMilliseconds` answers the **component** — the
+ * milliseconds inside the second, so `duration('123.321456789s').getMilliseconds()` is 321
+ * and not 123,321.
+ *
+ * That split is cel-spec's, and it is also the only reading under which the engine does not
+ * contradict itself: a timestamp's `getMilliseconds()` has always answered the component.
+ */
+export function durationField(value, field) {
+    const total = durationNanos(value);
+    switch (field) {
+        case "getHours":
+            return total / 3600000000000n;
+        case "getMinutes":
+            return total / 60000000000n;
+        case "getSeconds":
+            return total / NANOS_PER_SECOND;
+        case "getMilliseconds":
+            return BigInt(Math.trunc(value.nanos / 1_000_000));
+    }
+}

package/dist/emitted-module.d.ts

@@ -0,0 +1,207 @@
+/**
+ * An emitted module: its text, its key, its integrity header, and the one seam a host
+ * stores it through.
+ *
+ * **The runtime is injected, never imported.** The module's default export is a factory
+ * taking the runtime support library and answering one synchronous function per
+ * expression, and the text names no specifier of any kind. An emitted module that imported
+ * `@telorun/cel` would be loadable only where that specifier resolves — which rules out a
+ * `data:` URL, a cache directory mounted somewhere else, and a host whose resolver is not
+ * Node's — and, worse, it would silently accept a runtime of another version, which is
+ * precisely what the key cannot see from the outside.
+ *
+ * **The key is wider than the source text, and the header is wider than the key.** The key
+ * is a hash over the emitter's format generation, the engine version, the environment
+ * digest and the canonical ordered list of expression sources. A key is a claim about a
+ * *name*; the header is a fact about the *bytes*, and it carries five fields because the
+ * provenance three answer only part of the question:
+ *
+ * - `format`, `engine`, `environment` — **provenance**. These are identical for every module
+ *   one engine writes against one environment, so they catch a cache root shared by two
+ *   engines and a stale environment, and **nothing else**. Two different modules of one
+ *   engine carry byte-identical provenance.
+ * - `key` — the module's **identity**: the key this text was written for. It catches a store
+ *   that answered one key's lookup with another key's text, which the provenance fields
+ *   cannot see at all and which an expression count can only catch by luck.
+ * - `body` — the digest of the text **following the header line**, which covers every byte
+ *   that is or could be read as code, the `integrity` export included. It catches a text
+ *   truncated after its header and a text edited after it was written — and the banner says
+ *   *edit the expression, not this*, which is evidence that someone will edit one. A text with
+ *   an intact header, an exported factory and a matching function count **runs**, whatever its
+ *   body says; that is the one failure here no retry undoes.
+ *
+ * `body` cannot live in the `integrity` export, because it covers that export: a digest in the
+ * bytes it digests has no fixed point. So the header LINE carries all five and the export
+ * carries the four that are checkable without the text — which is also the split between the
+ * two paths. **Every mismatch on the store-read path is a recompile** that names itself in
+ * `refused`; the load path, which has an object and not the bytes, refuses with
+ * `emitted_module_rejected`.
+ *
+ * **There is no loader, and there is no filesystem.** A loader would have to reach a
+ * filesystem (which this package may not), or be `eval` (which the closure backend exists
+ * to avoid), or be a `data:` URL import (fine under Node, refused under a browser's content
+ * security policy). Loading is the host's half; the engine writes the text, verifies what
+ * comes back, and wires the loaded factory to the runtime.
+ */
+import type { CelProgram } from "./cel-program.js";
+import { type CelStep, type CompileTarget } from "./backend-runtime.js";
+import { type RuntimeBinding } from "./js-emitter.js";
+import type { CelNode } from "./syntax-tree.js";
+/**
+ * **Bumped on any change to the text the emitter writes for any tree** — not only when the
+ * module's shape changes. It is the first component of the key and the first field of the
+ * header, so a module written under one generation is never handed to an engine expecting
+ * another.
+ *
+ * The wider rule is the one that holds, because the narrower one asks whoever makes the
+ * change to decide that a text difference is semantically neutral — and that judgement is
+ * exactly what produces the unrecoverable failure. The case in point is this emitter's own
+ * first defect: temporaries numbered per function let a comprehension body's `let t0` shadow
+ * the `t0` its caller held a bound value in, so `cel.bind(n, 2, xs.map(e, e + n))` answered
+ * `[2, 4, 6]` for `[3, 4, 5]`. No signature moved, no library entry moved, no shape changed —
+ * and a module cached before the fix would have gone on answering `[2, 4, 6]` forever.
+ *
+ * `tests/emitter-text.test.ts` is what makes the rule checkable: it pins the digest of the
+ * code the emitter writes for a corpus drawn from the package's own total enumerations, beside
+ * this number, so a change to that text fails naming the bump it owes.
+ */
+export declare const EMITTER_FORMAT_GENERATION = 1;
+/**
+ * What an emitted module declares about itself in its `integrity` export: its provenance and
+ * its own key. These are the four a loaded module can be held to, because checking them needs
+ * nothing but the object the host imported.
+ */
+export interface EmittedIdentity {
+    readonly format: number;
+    readonly engine: string;
+    readonly environment: string;
+    /** The cache key this text was written for. */
+    readonly key: string;
+}
+/**
+ * What the header LINE declares: the identity, plus the digest of the body it precedes. The
+ * body digest is here and nowhere else — a digest cannot live in the bytes it covers — so it
+ * is verified on the one path that has the bytes in hand.
+ */
+export interface EmittedHeader extends EmittedIdentity {
+    /** The digest of every byte after the header line. */
+    readonly body: string;
+}
+/** One expression to emit: its source text, and the tree it read into. */
+export interface EmittedExpression {
+    readonly source: string;
+    readonly root: CelNode;
+}
+export interface EmittedModule {
+    /** The cache key: 64 hexadecimal characters a host names its stored copy by. */
+    readonly key: string;
+    readonly header: EmittedHeader;
+    readonly text: string;
+    /** The expression sources, in the order the factory answers functions for them. */
+    readonly sources: readonly string[];
+}
+/**
+ * Where a host keeps emitted module text, keyed by the key the engine computed. It is the
+ * engine's only seam to a store, and the engine touches no filesystem itself.
+ *
+ * **A write is atomic** — written elsewhere and renamed into place — and that is the store's
+ * contract rather than a suggestion: several hosts share one cache root. It is still how a
+ * half-written entry is *avoided*, and avoiding one is better than detecting it. But the
+ * guarantee no longer rests on it: the header's `body` digest **detects** a truncated or
+ * edited text, so a host that gets the write wrong costs a recompile rather than running
+ * whatever the bytes happen to say.
+ *
+ * It is **synchronous**, because emission is: a store over a filesystem writes and renames
+ * synchronously, and a store over anything slower is a map the host filled before it asked.
+ */
+export interface EmittedModuleStore {
+    read(key: string): string | undefined;
+    write(key: string, text: string): void;
+}
+/** A module taken from the store, or emitted because the store had nothing usable. */
+export interface StoredEmittedModule extends EmittedModule {
+    /** Why the stored copy was not used, where there was one and it was refused. */
+    readonly refused?: string;
+    /** Whether the text was emitted now rather than read from the store. */
+    readonly emitted: boolean;
+}
+/** The runtime object an emitted module's factory is handed. */
+export type EmittedRuntime = Readonly<Record<RuntimeBinding, unknown>>;
+/** What an emitted module's default export is. */
+export type EmittedFactory = (runtime: EmittedRuntime) => readonly CelStep[];
+/**
+ * The key for a set of expressions against an environment.
+ *
+ * The four components are hashed in one order, each on its own line with its source
+ * escaped, so no expression's text can be read as another component. Source alone would
+ * serve the wrong module for exactly the capability this package exists for — a host that
+ * replaced a standard function has the same text and a different environment.
+ */
+export declare function emittedModuleKey(environmentDigest: string, sources: readonly string[]): string;
+/** What an emission against this environment, for these sources, declares about itself. */
+export declare function emittedModuleIdentity(environmentDigest: string, sources: readonly string[]): EmittedIdentity;
+/**
+ * The header a stored text declares, or nothing where it declares none.
+ *
+ * It is read from the **text**, before anything is loaded: a text whose header is wrong is
+ * never handed to a loader at all, which is the cheapest place to refuse and the only place
+ * that works for a text that would not even parse.
+ */
+export declare function readEmittedHeader(text: string): EmittedHeader | undefined;
+/**
+ * Why a stored text is not the module that was asked for, or nothing where it is.
+ *
+ * This is the **store-read path**, the one that has the bytes, so it is where the body digest
+ * is verified as well as the identity — and every answer is a recompile, never a refusal the
+ * caller has to handle. Each names what differed, because a host that logs a recompile wants
+ * to know whether it was a stale cache, two engines sharing a root, a store that answered the
+ * wrong lookup, or a text somebody edited.
+ */
+export declare function emittedModuleRefusal(text: string, expected: EmittedIdentity): string | undefined;
+/**
+ * One module for a set of expressions. Byte-identical for the same expressions in the same
+ * order against the same environment: nothing here reads a clock, a counter outside the
+ * emission, or the iteration order of anything the caller did not order.
+ */
+export declare function emitModule(target: CompileTarget, environmentDigest: string, expressions: readonly EmittedExpression[]): EmittedModule;
+/**
+ * The module for a set of expressions, from the store where it holds a copy whose header
+ * matches, and emitted and written where it does not.
+ *
+ * The header check is what makes this safe to call on a shared cache root: a stored text
+ * that does not prove it was emitted by this engine, in this format, against this
+ * environment is replaced rather than run.
+ */
+export declare function storedEmittedModule(target: CompileTarget, environmentDigest: string, sources: readonly string[], 
+/** The trees, read only where there is something to emit — a hit parses nothing. */
+expressions: () => readonly EmittedExpression[], store: EmittedModuleStore): StoredEmittedModule;
+/**
+ * The runtime support library an emitted module's factory takes: every operation the
+ * emitted code calls, bound to this environment.
+ *
+ * Each entry is the function the **closure backend** calls for the same operation —
+ * literally the same reference — which is what makes "the two backends answer identically"
+ * a property of the wiring rather than a hope the tests confirm.
+ */
+export declare function emitterRuntime(target: CompileTarget): EmittedRuntime;
+/**
+ * The programs a loaded emitted module answers, after its header is verified.
+ *
+ * This is the **load path**: it has an object the host imported and not the bytes, so it
+ * checks the four fields the `integrity` export carries. A module that declares no header,
+ * declares another format, engine or environment, declares **another key** — which is a host
+ * that imported bytes this engine never hashed — exports no factory, or answers a different
+ * number of functions than the expressions asked for is refused with
+ * `emitted_module_rejected`. The function count stays as the cheap backstop; the `key` field
+ * is what actually distinguishes two modules of one engine.
+ *
+ * The body digest is **not** checked here, and cannot be: it covers the `integrity` export,
+ * so it lives only in the header line and is verified where the bytes are
+ * (`emittedModuleRefusal`, on the store-read path). Nothing here imports or evaluates
+ * anything; the module arrived already loaded, by whatever means the host loads one.
+ */
+export declare function programsFromEmittedModule(loaded: {
+    readonly integrity?: unknown;
+    readonly default?: unknown;
+}, expected: EmittedModule, runtime: EmittedRuntime): readonly CelProgram[];
+//# sourceMappingURL=emitted-module.d.ts.map

package/dist/emitted-module.d.ts.map

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