@usine/expression 0.2.0 → 0.4.0

package/README.md

@@ -1,17 +1,17 @@
 # @usine/expression
 
-Typed CEL checking and evaluation for [usine](https://github.com/basaltbytes/usine). Callers describe object types and root variables with `Environment`, then use `ExpressionEngine` to check boolean trigger expressions, check scalar prompt expressions, or evaluate either form over plain JSON.
+Typed CEL checking and evaluation for [usine](https://github.com/basaltbytes/usine). Describe types and root variables with `Environment`. `ExpressionEngine` then checks boolean trigger and scalar prompt expressions, and evaluates them over plain JSON.
 
-Unknown variables and object paths fail during checking, including paths inside CEL macros such as `exists`. Failures are typed values: `ExpressionCheckError` from parsing, type checking, or result-type checking, `ExpressionEvaluationError` from evaluation, and the `ExpressionError` union covering both. JSON integers declared as CEL `int` or `uint` are converted to `bigint` before evaluation so GraphQL payloads keep CEL integer semantics.
+Import `ExpressionEngine`, `Source`, `Environment`, the environment descriptors, `Scalar`, and the typed errors from `@usine/expression/expression-engine`, which replaces `@usine/expression/model`. The CEL adapter layer is in `@usine/expression/marcbachmann-cel`.
 
-`relatedStringLiterals(source, memberPath)` reports string literals from the smallest expression subtrees that use a member path. Config validation uses it to diagnose undeclared GitHub labels without coupling `@usine/config` to the CEL adapter's AST.
+A `nullable` `ObjectField` can be `null`, and an absent key reads as `null`. Expressions compare it with `null` in either order, and paths below it stay type-checked. Unknown variables and paths fail checking, also inside macros such as `exists`.
 
-`MarcbachmannCelLayer` uses `@marcbachmann/cel-js@8.0.0`. The exported `ExpressionEngine` contract contains CEL type names and usine-owned descriptors rather than library objects; an `@bufbuild/cel` adapter can provide the same service tag without changing callers.
+Expressions can use CEL optional values: `.?` and `[?]` select a value that might be missing, and `optional` helpers such as `orValue` give a fallback. `item.?milestone.?title.orValue("none")` is `"none"` if `milestone` is null or absent. A null field counts as present, so `item.?milestone` holds `null`, not an empty optional.
 
-All APIs remain 0.x and can change between minor releases.
+Errors: `ExpressionCheckError` (parse, type, or result type), `ExpressionEvaluationError`, and the union `ExpressionError`. JSON integers declared as CEL `int` or `uint` become `bigint` before evaluation, so GraphQL payloads keep CEL integer semantics.
 
-Import `ExpressionEngine`, `Source`, `Environment`, the environment descriptors,
-`Scalar`, and the typed expression errors from `@usine/expression/expression-engine`.
-This entry point replaces `@usine/expression/model`; existing imports from that
-subpath must use `/expression-engine`. Import the CEL adapter layer separately
-from `@usine/expression/marcbachmann-cel`.
+`relatedStringLiterals(source, memberPath)` returns string literals from the smallest subtrees that use a member path. It accepts the same syntax as the checks, including `.?`. Config validation uses it to report undeclared labels without depending on the CEL AST.
+
+`MarcbachmannCelLayer` uses `@marcbachmann/cel-js@8.0.0`. The contract uses CEL type names and usine descriptors, not library objects; an `@bufbuild/cel` adapter can provide the same tag.
+
+The 0.x APIs can change between minor releases.

package/dist/environment.d.ts

@@ -1,33 +1,43 @@
 import { Schema } from "effect";
-/** A type name in CEL syntax such as `string`, `Issue`, or `list<Label>`. */
+/**
+ * A CEL type name without spaces, such as `string`, `Label`, `list<T>`, or `map<K,V>`.
+ * Decoding checks only the syntax; an undeclared object type fails when an expression is checked.
+ */
 export declare const TypeReference: Schema.brand<Schema.String, "CelTypeReference">;
 export type TypeReference = typeof TypeReference.Type;
 declare const ObjectField_base: Schema.Class<ObjectField, Schema.Struct<{
     readonly name: Schema.String;
+    /** The CEL type of a non-`null` value. */
     readonly type: Schema.brand<Schema.String, "CelTypeReference">;
+    /** Whether the value can be `null` or absent. Reading an absent non-nullable field fails evaluation. */
+    readonly nullable: Schema.withConstructorDefault<Schema.Boolean>;
 }>, {}>;
-/** One named field and its CEL type within an object descriptor. */
+/** A field of an {@link ObjectType}. If the field is nullable and its key is absent, it evaluates to `null`. */
 export declare class ObjectField extends ObjectField_base {
 }
 declare const ObjectType_base: Schema.Class<ObjectType, Schema.Struct<{
     readonly name: Schema.String;
     readonly fields: Schema.$Array<typeof ObjectField>;
 }>, {}>;
-/** A CEL object type. Declare a type before the types that reference it. */
+/** An object type that expressions can read fields from, such as `IssuePayload`. */
 export declare class ObjectType extends ObjectType_base {
 }
 declare const Variable_base: Schema.Class<Variable, Schema.Struct<{
     readonly name: Schema.String;
     readonly type: Schema.brand<Schema.String, "CelTypeReference">;
 }>, {}>;
-/** A root variable available to CEL expressions in an Environment. */
+/** A root variable, such as `repo` or `item`, whose value is the `context` entry with the same name. */
 export declare class Variable extends Variable_base {
 }
 declare const Environment_base: Schema.Class<Environment, Schema.Struct<{
+    /** The object types, each declared before any type whose fields reference it. */
     readonly types: Schema.$Array<typeof ObjectType>;
     readonly variables: Schema.$Array<typeof Variable>;
 }>, {}>;
-/** The types and root variables an expression is checked and evaluated against. */
+/**
+ * The types and root variables that expressions are checked and evaluated against. An
+ * expression that references anything else fails checking.
+ */
 export declare class Environment extends Environment_base {
 }
 export {};

package/dist/environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,6EAA6E;AAC7E,eAAO,MAAM,aAAa,iDAKc,CAAC;AACzC,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;;;;;AAkBtD,oEAAoE;AACpE,qBAAa,WAAY,SAAQ,gBAG/B;CAAG;;;;;AAEL,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,eAG9B;CAAG;;;;;AAEL,sEAAsE;AACtE,qBAAa,QAAS,SAAQ,aAG5B;CAAG;;;;;AAEL,mFAAmF;AACnF,qBAAa,WAAY,SAAQ,gBAG/B;CAAG"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,aAAa,iDAKc,CAAC;AACzC,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;;;IAqBpD,0CAA0C;;IAE1C,wGAAwG;;;AAL1G,gHAAgH;AAChH,qBAAa,WAAY,SAAQ,gBAM/B;CAAG;;;;;AAEL,oFAAoF;AACpF,qBAAa,UAAW,SAAQ,eAG9B;CAAG;;;;;AAEL,wGAAwG;AACxG,qBAAa,QAAS,SAAQ,aAG5B;CAAG;;IAOH,iFAAiF;;;;AALnF;;;GAGG;AACH,qBAAa,WAAY,SAAQ,gBAI/B;CAAG"}

package/dist/environment.js

@@ -1,31 +1,41 @@
-import { Schema } from "effect";
-/** A type name in CEL syntax such as `string`, `Issue`, or `list<Label>`. */
+import { Effect, Schema } from "effect";
+/**
+ * A CEL type name without spaces, such as `string`, `Label`, `list<T>`, or `map<K,V>`.
+ * Decoding checks only the syntax; an undeclared object type fails when an expression is checked.
+ */
 export const TypeReference = Schema.String.check(Schema.isPattern(/^(?:[A-Za-z_][A-Za-z0-9_.]*|list<[A-Za-z_][A-Za-z0-9_.]*>|map<[A-Za-z_][A-Za-z0-9_.]*,[A-Za-z_][A-Za-z0-9_.]*>)$/u, { message: "Expected a CEL type reference" })).pipe(Schema.brand("CelTypeReference"));
 const Identifier = Schema.String.check(Schema.isPattern(/^[A-Za-z_][A-Za-z0-9_]*$/u, { message: "Expected a CEL identifier" }));
 const ObjectTypeName = Schema.String.check(Schema.isPattern(/^[A-Za-z_][A-Za-z0-9_.]*$/u, {
     message: "Expected a CEL object-type name",
 }));
 const uniqueNames = (message) => Schema.makeFilter((values) => new Set(values.map(({ name }) => name)).size === values.length, { message });
-/** One named field and its CEL type within an object descriptor. */
+/** A field of an {@link ObjectType}. If the field is nullable and its key is absent, it evaluates to `null`. */
 export class ObjectField extends Schema.Class("@usine/expression/ObjectField")({
     name: Identifier,
+    /** The CEL type of a non-`null` value. */
     type: TypeReference,
+    /** Whether the value can be `null` or absent. Reading an absent non-nullable field fails evaluation. */
+    nullable: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
 }) {
 }
-/** A CEL object type. Declare a type before the types that reference it. */
+/** An object type that expressions can read fields from, such as `IssuePayload`. */
 export class ObjectType extends Schema.Class("@usine/expression/ObjectType")({
     name: ObjectTypeName,
     fields: Schema.Array(ObjectField).check(uniqueNames("Expected unique CEL object-field names")),
 }) {
 }
-/** A root variable available to CEL expressions in an Environment. */
+/** A root variable, such as `repo` or `item`, whose value is the `context` entry with the same name. */
 export class Variable extends Schema.Class("@usine/expression/Variable")({
     name: Identifier,
     type: TypeReference,
 }) {
 }
-/** The types and root variables an expression is checked and evaluated against. */
+/**
+ * The types and root variables that expressions are checked and evaluated against. An
+ * expression that references anything else fails checking.
+ */
 export class Environment extends Schema.Class("@usine/expression/Environment")({
+    /** The object types, each declared before any type whose fields reference it. */
     types: Schema.Array(ObjectType).check(uniqueNames("Expected unique CEL object-type names")),
     variables: Schema.Array(Variable).check(uniqueNames("Expected unique CEL variable names")),
 }) {

package/dist/environment.js.map

@@ -1 +1 @@
-{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC9C,MAAM,CAAC,SAAS,CACd,mHAAmH,EACnH,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAC7C,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAGzC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACpC,MAAM,CAAC,SAAS,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC,CACxF,CAAC;AAEF,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACxC,MAAM,CAAC,SAAS,CAAC,4BAA4B,EAAE;IAC7C,OAAO,EAAE,iCAAiC;CAC3C,CAAC,CACH,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,OAAe,EAAE,EAAE,CACtC,MAAM,CAAC,UAAU,CACf,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAC1E,EAAE,OAAO,EAAE,CACZ,CAAC;AAEJ,oEAAoE;AACpE,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,KAAK,CAAc,+BAA+B,CAAC,CAAC;IAC1F,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,aAAa;CACpB,CAAC;CAAG;AAEL,4EAA4E;AAC5E,MAAM,OAAO,UAAW,SAAQ,MAAM,CAAC,KAAK,CAAa,8BAA8B,CAAC,CAAC;IACvF,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,wCAAwC,CAAC,CAAC;CAC/F,CAAC;CAAG;AAEL,sEAAsE;AACtE,MAAM,OAAO,QAAS,SAAQ,MAAM,CAAC,KAAK,CAAW,4BAA4B,CAAC,CAAC;IACjF,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,aAAa;CACpB,CAAC;CAAG;AAEL,mFAAmF;AACnF,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,KAAK,CAAc,+BAA+B,CAAC,CAAC;IAC1F,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,uCAAuC,CAAC,CAAC;IAC3F,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,oCAAoC,CAAC,CAAC;CAC3F,CAAC;CAAG"}
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC9C,MAAM,CAAC,SAAS,CACd,mHAAmH,EACnH,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAC7C,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAGzC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACpC,MAAM,CAAC,SAAS,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC,CACxF,CAAC;AAEF,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACxC,MAAM,CAAC,SAAS,CAAC,4BAA4B,EAAE;IAC7C,OAAO,EAAE,iCAAiC;CAC3C,CAAC,CACH,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,OAAe,EAAE,EAAE,CACtC,MAAM,CAAC,UAAU,CACf,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAC1E,EAAE,OAAO,EAAE,CACZ,CAAC;AAEJ,gHAAgH;AAChH,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,KAAK,CAAc,+BAA+B,CAAC,CAAC;IAC1F,IAAI,EAAE,UAAU;IAChB,0CAA0C;IAC1C,IAAI,EAAE,aAAa;IACnB,wGAAwG;IACxG,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;CACpF,CAAC;CAAG;AAEL,oFAAoF;AACpF,MAAM,OAAO,UAAW,SAAQ,MAAM,CAAC,KAAK,CAAa,8BAA8B,CAAC,CAAC;IACvF,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,wCAAwC,CAAC,CAAC;CAC/F,CAAC;CAAG;AAEL,wGAAwG;AACxG,MAAM,OAAO,QAAS,SAAQ,MAAM,CAAC,KAAK,CAAW,4BAA4B,CAAC,CAAC;IACjF,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,aAAa;CACpB,CAAC;CAAG;AAEL;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,KAAK,CAAc,+BAA+B,CAAC,CAAC;IAC1F,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,uCAAuC,CAAC,CAAC;IAC3F,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,oCAAoC,CAAC,CAAC;CAC3F,CAAC;CAAG"}

package/dist/expression-engine.d.ts

@@ -1,52 +1,82 @@
-import { Context, type Effect, Schema } from "effect";
+import { Context, type Effect, type Result, Schema } from "effect";
 import type { Environment } from "./environment.ts";
-/** Non-blank CEL source text. */
+/**
+ * The text of a CEL expression, such as a Loop's `if:` condition or a `{{ }}` interpolation.
+ * Decoding rejects blank text; {@link ExpressionEngine} checks syntax and types.
+ */
 export declare const Source: Schema.brand<Schema.String, "ExpressionSource">;
 export type Source = typeof Source.Type;
-/** Whether checking failed during parsing, type resolution, or result-type validation. */
+/**
+ * - `parse_error`: the source is not valid CEL syntax.
+ * - `type_error`: the source references an unknown variable or field, or combines
+ *   incompatible types.
+ * - `unexpected_result_type`: the result type is wrong for the operation, such as a non-`bool`
+ *   selection condition.
+ * - `check_failed`: the CEL implementation rejected the {@link Environment} itself, such as an
+ *   undeclared type name, or failed without a detail.
+ */
 export declare const CheckErrorCode: Schema.Literals<readonly ["check_failed", "parse_error", "type_error", "unexpected_result_type"]>;
 export type CheckErrorCode = typeof CheckErrorCode.Type;
 declare const ExpressionCheckError_base: Schema.Class<ExpressionCheckError, Schema.TaggedStruct<"ExpressionCheckError", {
     readonly source: Schema.brand<Schema.String, "ExpressionSource">;
     readonly code: Schema.Literals<readonly ["check_failed", "parse_error", "type_error", "unexpected_result_type"]>;
+    /**
+     * A human-readable description, possibly multi-line with a marked excerpt of `source`. The
+     * wording isn't stable; branch on `code`.
+     */
     readonly message: Schema.NonEmptyString;
+    /**
+     * The zero-based offset in `source` where the failure starts. Always `None` for
+     * `unexpected_result_type` and `check_failed`.
+     */
     readonly position: Schema.Option<Schema.Int>;
 }>, import("effect/Cause").YieldableError>;
-/** The expression failed to parse, to type-check, or to produce the expected result type. */
+/** An error from checking an expression against an {@link Environment}; checking never reads a payload. */
 export declare class ExpressionCheckError extends ExpressionCheckError_base {
 }
 declare const ExpressionEvaluationError_base: Schema.Class<ExpressionEvaluationError, Schema.TaggedStruct<"ExpressionEvaluationError", {
     readonly source: Schema.brand<Schema.String, "ExpressionSource">;
+    /** A human-readable description, possibly multi-line with a marked excerpt of `source`. The wording isn't stable. */
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** Evaluation failed on an expression that had already checked. */
+/**
+ * An error from evaluating a checked expression, such as a missing `context` key, a value of the
+ * wrong type, division by zero, or an out-of-range list index.
+ */
 export declare class ExpressionEvaluationError extends ExpressionEvaluationError_base {
 }
-/** The failures callers can receive when checking or evaluating a CEL expression. */
 export declare const ExpressionError: Schema.Union<readonly [typeof ExpressionCheckError, typeof ExpressionEvaluationError]>;
 export type ExpressionError = typeof ExpressionError.Type;
-/** Values prompt interpolation can render. CEL ints stay bigint. */
+/**
+ * The result of a prompt interpolation; CEL `int` is a `bigint` and `double` is a `number`. A
+ * `uint` result passes `checkScalar`, but `evaluateScalar` fails with
+ * {@link ExpressionEvaluationError}; wrap it in `string(...)` or `double(...)`.
+ */
 export declare const Scalar: Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>;
 export type Scalar = typeof Scalar.Type;
-/** Checks and evaluates the expressions used to select Items and fill Loop task templates. */
 export interface ExpressionEngineService {
     /**
-     * The string literals the expression compares against the `name` field of
-     * values reached from `memberPath`, following macro bindings and collection
-     * transformations. Config validation uses it to spot undeclared labels.
+     * Returns the string literals compared with the `name` field of values under `memberPath`,
+     * following macro bindings and collection transformations. Accepts the same syntax as
+     * `checkBoolean` and `checkScalar`, including optional selection (`.?`).
      */
     readonly relatedStringLiterals: (source: Source, memberPath: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, ExpressionCheckError>;
-    /** Checks whether the expression can select Items, without evaluating a payload. */
+    /** Checks that the expression has type `bool`. */
     readonly checkBoolean: (source: Source, environment: Environment) => Effect.Effect<void, ExpressionCheckError>;
-    /** Checks whether the expression can produce one value for prompt interpolation. */
+    /** Checks that the expression can be a prompt interpolation. */
     readonly checkScalar: (source: Source, environment: Environment) => Effect.Effect<void, ExpressionCheckError>;
-    /** Checks and evaluates a selection condition; `context` supplies values for the environment's root variables. */
+    /** Checks and evaluates a selection condition against `context`. */
     readonly evaluateBoolean: (source: Source, environment: Environment, context: Schema.JsonObject) => Effect.Effect<boolean, ExpressionError>;
-    /** Checks and evaluates a prompt interpolation; `context` supplies values for the environment's root variables. */
+    /**
+     * Checks the condition once and evaluates it against each of `contexts`, returning one
+     * `Result` per context in order. Fails with `ExpressionCheckError` if the check fails.
+     */
+    readonly evaluateBooleanEach: (source: Source, environment: Environment, contexts: ReadonlyArray<Schema.JsonObject>) => Effect.Effect<ReadonlyArray<Result.Result<boolean, ExpressionEvaluationError>>, ExpressionCheckError>;
+    /** Checks and evaluates a prompt interpolation against `context`. */
     readonly evaluateScalar: (source: Source, environment: Environment, context: Schema.JsonObject) => Effect.Effect<Scalar, ExpressionError>;
 }
 declare const ExpressionEngine_base: Context.ServiceClass<ExpressionEngine, "@usine/expression/ExpressionEngine", ExpressionEngineService>;
-/** Evaluates Loop conditions and prompt expressions against their declared payload context. */
+/** The CEL expression service, provided by `MarcbachmannCelLayer` from `@usine/expression/marcbachmann-cel`. */
 export declare class ExpressionEngine extends ExpressionEngine_base {
 }
 export { TypeReference, ObjectField, ObjectType, Variable, Environment } from "./environment.ts";

package/dist/expression-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expression-engine.d.ts","sourceRoot":"","sources":["../src/expression-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,iCAAiC;AACjC,eAAO,MAAM,MAAM,iDAEqB,CAAC;AACzC,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAIxC,0FAA0F;AAC1F,eAAO,MAAM,cAAc,mGAKzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;;;;;;;AAExD,6FAA6F;AAC7F,qBAAa,oBAAqB,SAAQ,yBAOxC;CAAG;;;;;AAEL,mEAAmE;AACnE,qBAAa,yBAA0B,SAAQ,8BAK7C;CAAG;AAEL,qFAAqF;AACrF,eAAO,MAAM,eAAe,wFAAkE,CAAC;AAC/F,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC;AAE1D,oEAAoE;AACpE,eAAO,MAAM,MAAM,mGAMjB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAExC,8FAA8F;AAC9F,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC;IAChE,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,KACrB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC/C,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,CACpB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,KACrB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC/C,kHAAkH;IAClH,QAAQ,CAAC,eAAe,EAAE,CACxB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,CAAC,UAAU,KACvB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC7C,mHAAmH;IACnH,QAAQ,CAAC,cAAc,EAAE,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,CAAC,UAAU,KACvB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;;AAED,+FAA+F;AAC/F,qBAAa,gBAAiB,SAAQ,qBAErC;CAAG;AAEJ,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"expression-engine.d.ts","sourceRoot":"","sources":["../src/expression-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,MAAM,iDAEqB,CAAC;AACzC,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAIxC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,mGAKzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;;;;IAQtD;;;OAGG;;IAEH;;;OAGG;;;AAdL,2GAA2G;AAC3G,qBAAa,oBAAqB,SAAQ,yBAexC;CAAG;;;IAUH,qHAAqH;;;AARvH;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,8BAM7C;CAAG;AAEL,eAAO,MAAM,eAAe,wFAAkE,CAAC;AAC/F,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,MAAM,mGAMjB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAExC,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC;IAChE,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,KACrB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,CACpB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,KACrB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC/C,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,CACxB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,CAAC,UAAU,KACvB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,CAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,KACvC,MAAM,CAAC,MAAM,CAChB,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC,EAChE,oBAAoB,CACrB,CAAC;IACF,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,CAAC,UAAU,KACvB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;;AAED,gHAAgH;AAChH,qBAAa,gBAAiB,SAAQ,qBAErC;CAAG;AAEJ,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/expression-engine.js

@@ -1,31 +1,57 @@
 import { Context, Schema } from "effect";
-/** Non-blank CEL source text. */
+/**
+ * The text of a CEL expression, such as a Loop's `if:` condition or a `{{ }}` interpolation.
+ * Decoding rejects blank text; {@link ExpressionEngine} checks syntax and types.
+ */
 export const Source = Schema.String.check(Schema.isPattern(/\S/u, { message: "Expected a non-blank CEL expression" })).pipe(Schema.brand("ExpressionSource"));
 const Position = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
-/** Whether checking failed during parsing, type resolution, or result-type validation. */
+/**
+ * - `parse_error`: the source is not valid CEL syntax.
+ * - `type_error`: the source references an unknown variable or field, or combines
+ *   incompatible types.
+ * - `unexpected_result_type`: the result type is wrong for the operation, such as a non-`bool`
+ *   selection condition.
+ * - `check_failed`: the CEL implementation rejected the {@link Environment} itself, such as an
+ *   undeclared type name, or failed without a detail.
+ */
 export const CheckErrorCode = Schema.Literals([
     "check_failed",
     "parse_error",
     "type_error",
     "unexpected_result_type",
 ]);
-/** The expression failed to parse, to type-check, or to produce the expected result type. */
+/** An error from checking an expression against an {@link Environment}; checking never reads a payload. */
 export class ExpressionCheckError extends Schema.TaggedError("@usine/expression/ExpressionCheckError")("ExpressionCheckError", {
     source: Source,
     code: CheckErrorCode,
+    /**
+     * A human-readable description, possibly multi-line with a marked excerpt of `source`. The
+     * wording isn't stable; branch on `code`.
+     */
     message: Schema.NonEmptyString,
+    /**
+     * The zero-based offset in `source` where the failure starts. Always `None` for
+     * `unexpected_result_type` and `check_failed`.
+     */
     position: Schema.Option(Position),
 }) {
 }
-/** Evaluation failed on an expression that had already checked. */
+/**
+ * An error from evaluating a checked expression, such as a missing `context` key, a value of the
+ * wrong type, division by zero, or an out-of-range list index.
+ */
 export class ExpressionEvaluationError extends Schema.TaggedError("@usine/expression/ExpressionEvaluationError")("ExpressionEvaluationError", {
     source: Source,
+    /** A human-readable description, possibly multi-line with a marked excerpt of `source`. The wording isn't stable. */
     message: Schema.NonEmptyString,
 }) {
 }
-/** The failures callers can receive when checking or evaluating a CEL expression. */
 export const ExpressionError = Schema.Union([ExpressionCheckError, ExpressionEvaluationError]);
-/** Values prompt interpolation can render. CEL ints stay bigint. */
+/**
+ * The result of a prompt interpolation; CEL `int` is a `bigint` and `double` is a `number`. A
+ * `uint` result passes `checkScalar`, but `evaluateScalar` fails with
+ * {@link ExpressionEvaluationError}; wrap it in `string(...)` or `double(...)`.
+ */
 export const Scalar = Schema.Union([
     Schema.String,
     Schema.Number,
@@ -33,7 +59,7 @@ export const Scalar = Schema.Union([
     Schema.Boolean,
     Schema.Null,
 ]);
-/** Evaluates Loop conditions and prompt expressions against their declared payload context. */
+/** The CEL expression service, provided by `MarcbachmannCelLayer` from `@usine/expression/marcbachmann-cel`. */
 export class ExpressionEngine extends Context.Service()("@usine/expression/ExpressionEngine") {
 }
 export { TypeReference, ObjectField, ObjectType, Variable, Environment } from "./environment.js";

package/dist/expression-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"expression-engine.js","sourceRoot":"","sources":["../src/expression-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAe,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGtD,iCAAiC;AACjC,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACvC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAC5E,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAGzC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE,0FAA0F;AAC1F,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC5C,cAAc;IACd,aAAa;IACb,YAAY;IACZ,wBAAwB;CACzB,CAAC,CAAC;AAGH,6FAA6F;AAC7F,MAAM,OAAO,oBAAqB,SAAQ,MAAM,CAAC,WAAW,CAC1D,wCAAwC,CACzC,CAAC,sBAAsB,EAAE;IACxB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,MAAM,CAAC,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;CAClC,CAAC;CAAG;AAEL,mEAAmE;AACnE,MAAM,OAAO,yBAA0B,SAAQ,MAAM,CAAC,WAAW,CAC/D,6CAA6C,CAC9C,CAAC,2BAA2B,EAAE;IAC7B,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,qFAAqF;AACrF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,oBAAoB,EAAE,yBAAyB,CAAC,CAAC,CAAC;AAG/F,oEAAoE;AACpE,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;IACjC,MAAM,CAAC,MAAM;IACb,MAAM,CAAC,MAAM;IACb,MAAM,CAAC,MAAM;IACb,MAAM,CAAC,OAAO;IACd,MAAM,CAAC,IAAI;CACZ,CAAC,CAAC;AAsCH,+FAA+F;AAC/F,MAAM,OAAO,gBAAiB,SAAQ,OAAO,CAAC,OAAO,EAA6C,CAChG,oCAAoC,CACrC;CAAG;AAEJ,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"expression-engine.js","sourceRoot":"","sources":["../src/expression-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAA4B,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGnE;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACvC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAC5E,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAGzC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC5C,cAAc;IACd,aAAa;IACb,YAAY;IACZ,wBAAwB;CACzB,CAAC,CAAC;AAGH,2GAA2G;AAC3G,MAAM,OAAO,oBAAqB,SAAQ,MAAM,CAAC,WAAW,CAC1D,wCAAwC,CACzC,CAAC,sBAAsB,EAAE;IACxB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,cAAc;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC,cAAc;IAC9B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;CAClC,CAAC;CAAG;AAEL;;;GAGG;AACH,MAAM,OAAO,yBAA0B,SAAQ,MAAM,CAAC,WAAW,CAC/D,6CAA6C,CAC9C,CAAC,2BAA2B,EAAE;IAC7B,MAAM,EAAE,MAAM;IACd,qHAAqH;IACrH,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,oBAAoB,EAAE,yBAAyB,CAAC,CAAC,CAAC;AAG/F;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;IACjC,MAAM,CAAC,MAAM;IACb,MAAM,CAAC,MAAM;IACb,MAAM,CAAC,MAAM;IACb,MAAM,CAAC,OAAO;IACd,MAAM,CAAC,IAAI;CACZ,CAAC,CAAC;AAiDH,gHAAgH;AAChH,MAAM,OAAO,gBAAiB,SAAQ,OAAO,CAAC,OAAO,EAA6C,CAChG,oCAAoC,CACrC;CAAG;AAEJ,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/marcbachmann-cel.d.ts

@@ -1,5 +1,20 @@
 import { Layer } from "effect";
 import { ExpressionEngine } from "./expression-engine.ts";
-/** The ExpressionEngine implementation on @marcbachmann/cel-js. */
+/**
+ * Provides {@link ExpressionEngine} with `@marcbachmann/cel-js` 8.0.0
+ * ([ADR 0004](../../../docs/adr/0004-loop-files-markdown-cel-frontmatter.md)).
+ *
+ * Expressions can use CEL optional values, such as `item.?milestone.?title.orValue("none")`. A
+ * nullable field that holds `null` counts as present, so `item.?milestone` holds `null` and
+ * `item.?milestone.?title` is empty.
+ *
+ * Before evaluation, converts JSON integers to `bigint` wherever the {@link Environment}
+ * declares `int`, at any depth, and sets absent nullable fields to `null`. Values inside a
+ * `map<K,V>` aren't converted, so declare integer map values as `double`.
+ *
+ * `uint` isn't supported in `context`; declare such values as `int`. An expression that reads a
+ * non-nullable `uint` value type-checks but fails evaluation. On a nullable field, comparing with a
+ * `uint` literal works but `uint` arithmetic fails. A `uint` result fails `evaluateScalar`.
+ */
 export declare const MarcbachmannCelLayer: Layer.Layer<ExpressionEngine, never, never>;
 //# sourceMappingURL=marcbachmann-cel.d.ts.map

package/dist/marcbachmann-cel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marcbachmann-cel.d.ts","sourceRoot":"","sources":["../src/marcbachmann-cel.ts"],"names":[],"mappings":"AAOA,OAAO,EAAU,KAAK,EAAkB,MAAM,QAAQ,CAAC;AAEvD,OAAO,EACL,gBAAgB,EAKjB,MAAM,wBAAwB,CAAC;AA6XhC,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,6CAM/B,CAAC"}
+{"version":3,"file":"marcbachmann-cel.d.ts","sourceRoot":"","sources":["../src/marcbachmann-cel.ts"],"names":[],"mappings":"AASA,OAAO,EAAU,KAAK,EAAqC,MAAM,QAAQ,CAAC;AAE1E,OAAO,EACL,gBAAgB,EAKjB,MAAM,wBAAwB,CAAC;AAsjBhC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,6CAAqD,CAAC"}