effect 4.0.4 → 4.0.5

package/src/Match.ts

@@ -712,6 +712,26 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _, Args extends Array<a
 ) => [Ret] extends [[A] extends [never] ? any : A] ? Matcher<I, F, R, A, Pr, Ret, Args>
   : "withReturnType constraint does not extend Result type" = internal.withReturnType
 
+// `P` is a const type parameter, so object literals skip excess-property checks.
+// Reject pattern keys that no object variant of the input has. Functions,
+// refinements, and array patterns are not checked.
+type PatternKey<K> = K extends number ? `${K}` : K
+
+type PatternKeys<A> = object extends A ? PropertyKey
+  : A extends object ? PatternKey<keyof A>
+  : never
+
+type ObjectPatternGuard<A, P> = [P] extends [Function | ReadonlyArray<any> | SafeRefinement<never, any>] ? unknown
+  : [P] extends [object] ? { readonly [K in Exclude<PatternKey<keyof P>, PatternKeys<A>>]: never }
+  : unknown
+
+type ExactPattern<R, P> = (Types.PatternPrimitive<R> | Types.PatternBase<R>) & ObjectPatternGuard<R, P>
+
+type ExactPatterns<R, P> = {
+  readonly [I in keyof P]: I extends number | `${number}` ? P[I] & ExactPattern<R, P[I]>
+    : P[I]
+}
+
 /**
  * Defines a condition for matching values.
  *
@@ -763,7 +783,7 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _, Args extends Array<a
  */
 export const when: <
   R,
-  const P extends Types.PatternPrimitive<R> | Types.PatternBase<R>,
+  const P extends ExactPattern<R, P>,
   Ret,
   Args extends Array<any>,
   Fn extends (_: Types.WhenMatch<R, P>, ...args: Args) => Ret
@@ -831,7 +851,7 @@ export const whenOr: <
   Args extends Array<any>,
   Fn extends (_: Types.WhenMatch<R, P[number]>, ...args: Args) => Ret
 >(
-  ...args: [...patterns: P, f: Fn]
+  ...args: [...patterns: ExactPatterns<R, P>, f: Fn]
 ) => <I, F, A, Pr>(
   self: Matcher<I, F, R, A, Pr, Ret, Args>
 ) => Matcher<
@@ -842,7 +862,13 @@ export const whenOr: <
   Pr,
   Ret,
   Args
-> = internal.whenOr
+> = <
+  R,
+  const P extends ReadonlyArray<Types.PatternPrimitive<R> | Types.PatternBase<R>>,
+  Ret,
+  Args extends Array<any>,
+  Fn extends (_: Types.WhenMatch<R, P[number]>, ...args: Args) => Ret
+>(...args: [...patterns: ExactPatterns<R, P>, f: Fn]) => internal.whenOr<R, P, Ret, Args, Fn>(...args)
 
 /**
  * Matches a value that satisfies all provided patterns.
@@ -890,7 +916,7 @@ export const whenAnd: <
   Args extends Array<any>,
   Fn extends (_: Types.WhenMatch<R, T.UnionToIntersection<P[number]>>, ...args: Args) => Ret
 >(
-  ...args: [...patterns: P, f: Fn]
+  ...args: [...patterns: ExactPatterns<R, P>, f: Fn]
 ) => <I, F, A, Pr>(
   self: Matcher<I, F, R, A, Pr, Ret, Args>
 ) => Matcher<
@@ -901,7 +927,13 @@ export const whenAnd: <
   Pr,
   Ret,
   Args
-> = internal.whenAnd
+> = <
+  R,
+  const P extends ReadonlyArray<Types.PatternPrimitive<R> | Types.PatternBase<R>>,
+  Ret,
+  Args extends Array<any>,
+  Fn extends (_: Types.WhenMatch<R, T.UnionToIntersection<P[number]>>, ...args: Args) => Ret
+>(...args: [...patterns: ExactPatterns<R, P>, f: Fn]) => internal.whenAnd<R, P, Ret, Args, Fn>(...args)
 
 /**
  * Matches values based on a specified discriminant field.
@@ -1398,7 +1430,7 @@ export const tagsExhaustive: <
  */
 export const not: <
   R,
-  const P extends Types.PatternPrimitive<R> | Types.PatternBase<R>,
+  const P extends ExactPattern<R, P>,
   Ret,
   Args extends Array<any>,
   Fn extends (_: Types.NotMatch<R, P>, ...args: Args) => Ret
@@ -2835,6 +2867,32 @@ export declare namespace Types {
 
   type Simplify<A> = { [K in keyof A]: A[K] } & {}
 
+  // Tuple patterns match a prefix at runtime. For inputs with a variadic part,
+  // narrow each position the pattern requires and keep the rest of the input.
+  type NarrowArrayPattern<I extends ReadonlyArray<any>, P extends ReadonlyArray<any>> = number extends I["length"]
+    ? number extends P["length"] ? MapArrayPattern<I, P>
+    : P["length"] extends Required<P>["length"] ? NarrowArrayPrefix<I, P>
+    : MapArrayPattern<I, P>
+    : MapArrayPattern<I, P>
+
+  type MapArrayPattern<I, P> = {
+    readonly [K in keyof I]: K extends keyof P ? ExtractAndNarrow<I[K], P[K]> : I[K]
+  } extends infer R ? Fail extends R[keyof R] ? never
+    : R
+    : never
+
+  type NarrowArrayPrefix<
+    I extends ReadonlyArray<any>,
+    P extends ReadonlyArray<any>,
+    Out extends ReadonlyArray<any> = readonly []
+  > = P extends readonly [infer PH, ...infer PT] ?
+    I extends readonly [infer IH, ...infer IT] ?
+      [ExtractAndNarrow<IH, PH>] extends [infer N] ? [N] extends [never] ? never
+        : NarrowArrayPrefix<IT, PT, readonly [...Out, N]>
+      : never
+    : NarrowArrayPrefix<readonly [I[number], ...Array<I[number]>], P, Out>
+    : readonly [...Out, ...I]
+
   type ExtractAndNarrow<Input, P> = P extends Predicate.Refinement<infer _In, infer _Out> ?
     _Out extends Input ? Extract<_Out, Input>
     : Extract<Input, _Out> :
@@ -2843,12 +2901,7 @@ export declare namespace Types {
       : Extract<Input, _In>
     : P extends Predicate.Predicate<infer _In> ? Extract<Input, _In>
     : Input extends infer I ? Exclude<
-        I extends ReadonlyArray<any> ? P extends ReadonlyArray<any> ? {
-              readonly [K in keyof I]: K extends keyof P ? ExtractAndNarrow<I[K], P[K]>
-                : I[K]
-            } extends infer R ? Fail extends R[keyof R] ? never
-              : R
-            : never
+        I extends ReadonlyArray<any> ? P extends ReadonlyArray<any> ? NarrowArrayPattern<I, P>
           : never
           : IsPlainObject<I> extends true ? string extends keyof I ? I extends P ? I
               : never

package/src/Path.ts

@@ -14,6 +14,7 @@ import * as Context from "./Context.ts"
 import * as Effect from "./Effect.ts"
 import { identity } from "./Function.ts"
 import * as Layer from "./Layer.ts"
+import * as Option from "./Option.ts"
 import { BadArgument } from "./PlatformError.ts"
 
 /**
@@ -47,10 +48,17 @@ export const TypeId = "~effect/Path"
  * formatting, and converting file system paths. URL conversion methods return
  * `Effect`s because invalid file URLs or paths can fail with `BadArgument`.
  *
+ * `resolveWithin(root, input)` resolves a relative `input` beneath `root` and
+ * returns `Option.none()` when the result would leave the root or when `input`
+ * has its own root (an absolute path, or a Windows drive or UNC prefix). The
+ * root itself is allowed. The check is lexical: it does not follow symlinks,
+ * so it is not a sandbox on its own. A relative `root` is resolved against the
+ * current working directory, as with `resolve`.
+ *
  * **Example** (Using path operations)
  *
  * ```ts import.meta.vitest
- * import { Effect, Path } from "effect"
+ * import { Effect, Option, Path } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const path = yield* Path.Path
@@ -64,7 +72,8 @@ export const TypeId = "~effect/Path"
  *     isAbsolute: path.isAbsolute("/absolute/path"),
  *     name: path.parse("/path/to/file.txt").name,
  *     relative: path.relative("/from/path", "/to/path"),
- *     resolved: path.resolve("/base", "relative", "path")
+ *     resolved: path.resolve("/base", "relative", "path"),
+ *     within: path.resolveWithin("/base", "../outside")
  *   }
  * })
  *
@@ -78,6 +87,7 @@ export const TypeId = "~effect/Path"
  * result.name // => "file"
  * result.relative // => "../../to/path"
  * result.resolved // => "/base/relative/path"
+ * result.within // => Option.none()
  * ```
  *
  * @stability unstable
@@ -98,6 +108,7 @@ export interface Path {
   readonly parse: (path: string) => Path.Parsed
   readonly relative: (from: string, to: string) => string
   readonly resolve: (...pathSegments: ReadonlyArray<string>) => string
+  readonly resolveWithin: (root: string, input: string) => Option.Option<string>
   readonly toFileUrl: (path: string) => Effect.Effect<URL, BadArgument>
   readonly toNamespacedPath: (path: string) => string
 }
@@ -204,8 +215,7 @@ export declare namespace Path {
  * import { Effect, Layer, Path } from "effect"
  *
  * // Create a custom path implementation
- * const customPath: Path.Path = {
- *   [Path.TypeId]: Path.TypeId,
+ * const customPath = Path.make({
  *   sep: "/",
  *   basename: (path: string, suffix?: string) => {
  *     const base = path.split("/").pop() || ""
@@ -239,7 +249,7 @@ export declare namespace Path {
  *   resolve: (...pathSegments: ReadonlyArray<string>) => pathSegments.join("/"),
  *   toFileUrl: (path: string) => Effect.succeed(new URL(`file://${path}`)),
  *   toNamespacedPath: (path: string) => path
- * }
+ * })
  *
  * // Provide the path service
  * const customPathLayer = Layer.succeed(Path.Path)(customPath)
@@ -259,6 +269,42 @@ export declare namespace Path {
  */
 export const Path: Context.Service<Path, Path> = Context.Service("effect/Path")
 
+/**
+ * Creates a `Path` service from platform path operations.
+ *
+ * **When to use**
+ *
+ * Use to build a `Path` implementation, such as a platform layer or a test
+ * double, without implementing the operations that can be derived from the
+ * others.
+ *
+ * **Details**
+ *
+ * Adds the `Path` type marker and derives `resolveWithin` from the provided
+ * `parse`, `resolve`, `relative`, `isAbsolute`, and `sep`, so containment
+ * follows the same platform rules as those operations.
+ *
+ * @see {@link layer} for the built-in POSIX `Path` service layer
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (impl: Omit<Path, typeof TypeId | "resolveWithin">): Path =>
+  Path.of({
+    ...impl,
+    [TypeId]: TypeId,
+    resolveWithin(root, input) {
+      if (impl.parse(input).root !== "") return Option.none()
+      const base = impl.resolve(root)
+      const candidate = impl.resolve(base, input)
+      const relative = impl.relative(base, candidate)
+      return relative === ".." || relative.startsWith(`..${impl.sep}`) || impl.isAbsolute(relative)
+        ? Option.none()
+        : Option.some(candidate)
+    }
+  })
+
 /**
  * The following functions are adapted from the Node.js source code:
  * https://github.com/nodejs/node/blob/main/lib/internal/url.js
@@ -479,8 +525,7 @@ function encodePathChars(filepath: string) {
   return filepath
 }
 
-const posixImpl = Path.of({
-  [TypeId]: TypeId,
+const posixImpl = make({
   resolve,
   normalize(path) {
     if (path.length === 0) return "."

package/src/Schema.ts

@@ -36,6 +36,7 @@ import * as HashMap_ from "./HashMap.ts"
 import * as HashSet_ from "./HashSet.ts"
 import * as Cookies_ from "./http/Cookies.ts"
 import * as Headers_ from "./http/Headers.ts"
+import * as UrlParams_internal from "./http/internal/urlParams.ts"
 import * as UrlParams_ from "./http/UrlParams.ts"
 import { NodeInspectSymbol } from "./Inspectable.ts"
 import * as core from "./internal/core.ts"
@@ -5966,6 +5967,9 @@ export type DecodingDefaultOptions = {
 function toIssueEffect<A, R>(
   self: Effect.Effect<A, SchemaError, R>
 ): Effect.Effect<A, SchemaIssue.Issue, R> {
+  if (effectIsExit(self) && self._tag === "Success") {
+    return self as unknown as Exit_.Exit<A, SchemaIssue.Issue>
+  }
   return Effect.catchCause(self, (cause) => Effect.failCauseSync(() => Cause_.map(cause, (error) => error.issue)))
 }
 /**
@@ -6312,6 +6316,12 @@ type Flatten<Schemas> = Schemas extends readonly [infer Head, ...infer Tail]
   ? Head extends Union<infer Inner> ? [...Flatten<Inner>, ...Flatten<Tail>]
   : [Head, ...Flatten<Tail>]
   : []
+type DiscriminantKey<T extends PropertyKey> = T extends number ? `${T}` : T
+type EnsureUniqueDiscriminants<Tags extends ReadonlyArray<PropertyKey>, Seen = never> = Tags extends
+  readonly [infer Head extends PropertyKey, ...infer Tail extends ReadonlyArray<PropertyKey>]
+  ? [DiscriminantKey<Head> & Seen] extends [never] ? EnsureUniqueDiscriminants<Tail, Seen | DiscriminantKey<Head>>
+  : never
+  : unknown
 type MatchCasesResult<Cases> = {
   [K in keyof Cases]-?: NonNullable<Cases[K]> extends (...args: Array<any>) => infer R ? R : never
 }[keyof Cases]
@@ -6396,7 +6406,10 @@ export type toTaggedUnion<
  *
  * **Gotchas**
  *
- * Throws if multiple members use the same discriminant property key.
+ * Rejects overlapping discriminant types in known member tuples at compile
+ * time, including nested unions. Numeric and string values such as `1` and
+ * `"1"` count as duplicates. Also throws at runtime if multiple members use the
+ * same discriminant property key.
  *
  * **Example** (Adding tagged-union utilities to an existing union)
  *
@@ -6423,7 +6436,7 @@ export type toTaggedUnion<
  */
 export function toTaggedUnion<const Tag extends PropertyKey>(tag: Tag) {
   return <const Members extends ReadonlyArray<Constraint & { readonly Type: { readonly [K in Tag]: PropertyKey } }>>(
-    self: Union<Members>
+    self: Union<Members> & NoInfer<EnsureUniqueDiscriminants<TaggedUnionUtils<Tag, Members>["discriminants"]>>
   ): toTaggedUnion<Tag, Members> => {
     const cases: Record<PropertyKey, unknown> = {}
     const discriminants: Array<PropertyKey> = []
@@ -15221,9 +15234,9 @@ export const UrlParams: UrlParams = declare(
     toCodec: () =>
       link<UrlParams_.UrlParams>()(
         ArraySchema(Tuple([String, String])),
-        SchemaTransformation.transform({
+        SchemaTransformation.transform<UrlParams_.UrlParams, ReadonlyArray<readonly [string, string]>>({
           decode: UrlParams_.make,
-          encode: (self) => self.params
+          encode: (self) => self.params.map(([key, value]) => [key, UrlParams_internal.unwrap(value)])
         })
       )
   }

package/src/String.ts

@@ -1441,6 +1441,12 @@ export const stripMargin = (self: string): string => stripMarginWith(self, "|")
 /**
  * Converts a snake_case string to camelCase.
  *
+ * **Details**
+ *
+ * Keeps the first character, then replaces each later underscore and the
+ * character after it with that character uppercased. A trailing underscore is
+ * dropped. Input made only of an even number of underscores returns `""`.
+ *
  * **Example** (Converting snake_case to camelCase)
  *
  * ```ts import.meta.vitest
@@ -1455,10 +1461,10 @@ export const stripMargin = (self: string): string => stripMarginWith(self, "|")
  * @since 2.0.0
  */
 export const snakeToCamel = (self: string): string => {
-  if (self.length === 0) return self
+  if (self.length === 0 || (self.length % 2 === 0 && self[0] === "_" && /^_+$/.test(self))) return ""
   let str = self[0]
   for (let i = 1; i < self.length; i++) {
-    str += self[i] === "_" ? self[++i].toUpperCase() : self[i]
+    str += self[i] === "_" ? self.charAt(++i).toUpperCase() : self[i]
   }
   return str
 }
@@ -1466,6 +1472,12 @@ export const snakeToCamel = (self: string): string => {
 /**
  * Converts a snake_case string to PascalCase.
  *
+ * **Details**
+ *
+ * Uppercases the first character, then replaces each later underscore and the
+ * character after it with that character uppercased. A trailing underscore is
+ * dropped. Input made only of an even number of underscores returns `""`.
+ *
  * **Example** (Converting snake_case to PascalCase)
  *
  * ```ts import.meta.vitest
@@ -1480,10 +1492,10 @@ export const snakeToCamel = (self: string): string => {
  * @since 2.0.0
  */
 export const snakeToPascal = (self: string): string => {
-  if (self.length === 0) return self
+  if (self.length === 0 || (self.length % 2 === 0 && self[0] === "_" && /^_+$/.test(self))) return ""
   let str = self[0].toUpperCase()
   for (let i = 1; i < self.length; i++) {
-    str += self[i] === "_" ? self[++i].toUpperCase() : self[i]
+    str += self[i] === "_" ? self.charAt(++i).toUpperCase() : self[i]
   }
   return str
 }
@@ -1739,6 +1751,7 @@ const normalizeCase = (
   while (result.charAt(end - 1) === "\0") {
     end--
   }
+  if (start >= end) return ""
 
   // Transform each token independently.
   return result.slice(start, end).split("\0").map(transform).join(delimiter)

package/src/TxRef.ts

@@ -13,6 +13,7 @@
  * @since 4.0.0
  */
 import * as Effect from "./Effect.ts"
+import type { TransactionMetaInner } from "./Effect.ts"
 import { dual } from "./Function.ts"
 import { pipeArguments } from "./Pipeable.ts"
 import type { Pipeable } from "./Pipeable.ts"
@@ -140,10 +141,11 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
 })
 
 const journalEntry = <A>(state: Effect.Transaction["Service"], self: TxRef<A>) => {
-  let entry = state.journal.get(self)
+  const journal = (state as TransactionMetaInner).journal
+  let entry = journal.get(self)
   if (entry === undefined) {
     entry = { version: self.version, value: self.value, written: false }
-    state.journal.set(self, entry)
+    journal.set(self, entry)
   }
   return entry
 }

package/src/ai/AiError.ts

@@ -47,7 +47,9 @@ import * as Schema from "../Schema.ts"
 export const HttpRequestDetails = Schema.Struct({
   method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE", "QUERY"]),
   url: Schema.String,
-  urlParams: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
+  urlParams: Schema.Array(
+    Schema.Tuple([Schema.String, Schema.Union([Schema.String, Schema.Redacted(Schema.String)])])
+  ),
   hash: Schema.optional(Schema.String),
   headers: Schema.Record(
     Schema.String,

package/src/ai/Decision.ts

@@ -28,9 +28,23 @@ export type TypeId = "~effect/ai/Decision"
  */
 export const TypeId: TypeId = "~effect/ai/Decision"
 
+/**
+ * Decision instructions or descriptions: a string, JSON object, or JSON array.
+ *
+ * **Details**
+ *
+ * TypeScript interfaces lack the index signature required by `Schema.JsonObject`;
+ * use object literals, type aliases, or Schema types instead.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.5
+ */
+export type Description = string | Schema.JsonObject | Schema.JsonArray
+
 /**
  * Decision that assigns the input one label out of a set of criteria.
- * `criteria` maps labels to descriptions.
+ * `criteria` maps labels to descriptions; use `null` for a label without a description.
  *
  * @see {@link classify} for the constructor
  * @see {@link ClassifyAnswer} for the answer produced by this decision
@@ -41,13 +55,14 @@ export const TypeId: TypeId = "~effect/ai/Decision"
  */
 export interface Classify<Label extends string> {
   readonly _tag: "Classify"
-  readonly instructions: string
-  readonly criteria: { readonly [L in Label]: string }
+  readonly instructions: Description
+  readonly criteria: { readonly [L in Label]: Description | null }
 }
 
 /**
  * Decision that places the input on an ordered scale of criteria.
- * `criteria` lists levels from lowest to highest.
+ * `criteria` lists levels from lowest to highest, with labels for answers and
+ * descriptions for the provider.
  *
  * @see {@link rate} for the constructor
  * @see {@link RateAnswer} for the answer produced by this decision
@@ -58,8 +73,8 @@ export interface Classify<Label extends string> {
  */
 export interface Rate<Level extends string> {
   readonly _tag: "Rate"
-  readonly instructions: string
-  readonly criteria: ReadonlyArray<Level>
+  readonly instructions: Description
+  readonly criteria: ReadonlyArray<{ readonly label: Level; readonly description: Description }>
 }
 
 /**
@@ -76,10 +91,10 @@ export interface Rate<Level extends string> {
  */
 export interface Probability {
   readonly _tag: "Probability"
-  readonly instructions: string
+  readonly instructions: Description
   readonly criteria?: {
-    readonly false: string
-    readonly true: string
+    readonly false: Description
+    readonly true: Description
   } | undefined
 }
 
@@ -110,8 +125,9 @@ export interface ClassifyAnswer<Label extends string> {
 /**
  * Answer to a {@link Rate} decision.
  * `rating` is the probability-weighted position on the scale and may fall
- * between two levels, within `[0, criteria.length - 1]`. `label` is the level
- * with the highest probability, choosing the first criteria entry on ties.
+ * between two levels, within `[0, criteria.length - 1]`. `label` is the label
+ * of the level with the highest probability, choosing the first criteria entry
+ * on ties.
  * `confidence` is an optional, provider-defined measure in `[0, 1]`.
  *
  * @stability unstable
@@ -176,6 +192,7 @@ export interface Definition<Input extends Schema.Constraint, Decisions extends R
 
 /**
  * Creates a classification decision from labelled criteria.
+ * Descriptions can be `null` when the label needs no explanation.
  * Throws if fewer than two labels are supplied.
  *
  * **Example** (Choosing a department)
@@ -201,8 +218,8 @@ export interface Definition<Input extends Schema.Constraint, Decisions extends R
  * @since 4.0.0
  */
 export const classify = <Label extends string>(options: {
-  readonly instructions: string
-  readonly criteria: { readonly [L in Label]: string }
+  readonly instructions: Description
+  readonly criteria: { readonly [L in Label]: Description | null }
 }): Classify<Label> => {
   if (Object.keys(options.criteria).length < 2) {
     throw new Error("Decision.classify: criteria must contain at least two labels")
@@ -216,7 +233,9 @@ export const classify = <Label extends string>(options: {
 
 /**
  * Creates a rating decision from an ordered list of criteria.
- * Throws if fewer than two levels or duplicate levels are supplied.
+ * Strings serve as both label and description; use `{ label, description }`
+ * to separate them. Answers use the label.
+ * Throws if fewer than two levels or duplicate labels are supplied.
  *
  * **Example** (Rating frustration)
  *
@@ -229,6 +248,33 @@ export const classify = <Label extends string>(options: {
  * })
  * ```
  *
+ * **Example** (Describing levels with structure)
+ *
+ * ```ts
+ * import { Decision } from "effect/ai"
+ *
+ * const severity = Decision.rate({
+ *   instructions: "How severe is the reported issue?",
+ *   criteria: [
+ *     "cosmetic",
+ *     {
+ *       label: "degraded",
+ *       description: {
+ *         what: "Broken or degraded feature, but workaround exists",
+ *         examples: ["export fails in one browser but works in another"]
+ *       }
+ *     },
+ *     {
+ *       label: "blocking",
+ *       description: {
+ *         what: "Blocking issue; no workaround exists",
+ *         examples: ["cannot log in", "data loss"]
+ *       }
+ *     }
+ *   ]
+ * })
+ * ```
+ *
  * @see {@link classify} for unordered labels
  *
  * @stability unstable
@@ -236,19 +282,22 @@ export const classify = <Label extends string>(options: {
  * @since 4.0.0
  */
 export const rate = <const Level extends string>(options: {
-  readonly instructions: string
-  readonly criteria: ReadonlyArray<Level>
+  readonly instructions: Description
+  readonly criteria: ReadonlyArray<Level | { readonly label: Level; readonly description: Description }>
 }): Rate<Level> => {
   if (options.criteria.length < 2) {
     throw new Error("Decision.rate: criteria must contain at least two levels")
   }
-  if (new Set(options.criteria).size !== options.criteria.length) {
+  const criteria = options.criteria.map((level) =>
+    typeof level === "string" ? { label: level, description: level } : level
+  )
+  if (new Set(criteria.map((level) => level.label)).size !== criteria.length) {
     throw new Error("Decision.rate: criteria must contain distinct levels")
   }
   return {
     _tag: "Rate",
     instructions: options.instructions,
-    criteria: options.criteria
+    criteria
   }
 }
 
@@ -287,10 +336,10 @@ export const rate = <const Level extends string>(options: {
  * @since 4.0.0
  */
 export const probability = (options: {
-  readonly instructions: string
+  readonly instructions: Description
   readonly criteria?: {
-    readonly false: string
-    readonly true: string
+    readonly false: Description
+    readonly true: Description
   } | undefined
 }): Probability => ({
   _tag: "Probability",

package/src/ai/DecisionModel.ts

@@ -290,7 +290,7 @@ const validateAnswer = (
       return { label: answer.label, probabilities, ...(confidence === undefined ? undefined : { confidence }) }
     }
     case "Rate": {
-      const levels = decision.criteria
+      const levels = decision.criteria.map((level) => level.label)
       if (!isFiniteNumber(answer.rating) || answer.rating < 0 || answer.rating > levels.length - 1) {
         return invalidOutput(`Provider returned a rating outside [0, ${levels.length - 1}] for decision "${key}"`)
       }