effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/ErrorReporter.js

@@ -6,6 +6,10 @@ import * as LogLevel from "./LogLevel.js";
 /**
  * Runtime type identifier attached to `ErrorReporter` values.
  *
+ * **When to use**
+ *
+ * Use to compare or attach the runtime identifier for `ErrorReporter` values.
+ *
  * @category Type Identifiers
  * @since 4.0.0
  */
@@ -13,6 +17,11 @@ export const TypeId = "~effect/ErrorReporter";
 /**
  * Creates an `ErrorReporter` from a callback.
  *
+ * **When to use**
+ *
+ * Use to define how reported failures are forwarded to a logging, monitoring,
+ * or error-tracking backend.
+ *
  * **Details**
  *
  * The returned reporter automatically deduplicates causes and individual
@@ -33,6 +42,9 @@ export const TypeId = "~effect/ErrorReporter";
  * )
  * ```
  *
+ * @see {@link layer} for registering reporters in the environment
+ * @see {@link report} for manually reporting a `Cause`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -70,9 +82,8 @@ export const make = report => {
  *
  * **When to use**
  *
- * Prefer {@link layer} to configure reporters via the `Layer` API. Use this
- * reference directly only when you need low-level control (e.g. reading the
- * current reporters or swapping them inside a `FiberRef`).
+ * Use when low-level code needs to read or replace the current set of reporters
+ * directly.
  *
  * @category references
  * @since 4.0.0
@@ -81,6 +92,11 @@ export const CurrentErrorReporters = references.CurrentErrorReporters;
 /**
  * Creates a `Layer` that registers one or more `ErrorReporter`s.
  *
+ * **When to use**
+ *
+ * Use to provide one or more error reporters to effects that perform error
+ * reporting.
+ *
  * **Details**
  *
  * Reporters can be plain `ErrorReporter` values or effectful
@@ -119,6 +135,9 @@ export const CurrentErrorReporters = references.CurrentErrorReporters;
  * )
  * ```
  *
+ * @see {@link make} for creating an `ErrorReporter` from a callback
+ * @see {@link CurrentErrorReporters} for low-level access to the current reporters
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -135,8 +154,7 @@ export const layer = (reporters, options) => Layer.effect(CurrentErrorReporters,
  *
  * **When to use**
  *
- * This is useful when you want to report an error for observability without
- * actually failing the fiber.
+ * Use to report a failure for observability without failing the current fiber.
  *
  * **Example** (Reporting a cause manually)
  *
@@ -162,6 +180,11 @@ export const report = cause => Effect.withFiber(fiber => {
  * Runtime property key used to mark an object error as ignored by error
  * reporting.
  *
+ * **When to use**
+ *
+ * Use to suppress reporting for expected object errors, such as HTTP 404
+ * responses.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.ignore]` to `true` to prevent the error from being
@@ -178,6 +201,10 @@ export const report = cause => Effect.withFiber(fiber => {
  * }
  * ```
  *
+ * @see {@link isIgnored} for checking whether a value carries this annotation
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -186,6 +213,13 @@ export const ignore = "~effect/ErrorReporter/ignore";
  * Returns `true` if the given value has the `ErrorReporter.ignore` annotation
  * set to `true`.
  *
+ * **When to use**
+ *
+ * Use to check whether an error value is annotated to be skipped before
+ * forwarding it to error reporting code.
+ *
+ * @see {@link ignore} for the annotation key this predicate reads
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -193,6 +227,11 @@ export const isIgnored = u => typeof u === "object" && u !== null && ignore in u
 /**
  * Runtime property key used to override the severity level of an object error.
  *
+ * **When to use**
+ *
+ * Use to annotate object errors with the severity reporter callbacks should
+ * receive.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.severity]` to a valid `LogLevel.Severity` value.
@@ -208,6 +247,10 @@ export const isIgnored = u => typeof u === "object" && u !== null && ignore in u
  * }
  * ```
  *
+ * @see {@link getSeverity} for reading the severity stored under this key
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -216,6 +259,14 @@ export const severity = "~effect/ErrorReporter/severity";
  * Reads the `ErrorReporter.severity` annotation from an error object,
  * falling back to `"Info"` when the annotation is unset or invalid.
  *
+ * **When to use**
+ *
+ * Use to inspect the severity that reporter callbacks will receive for an
+ * object error.
+ *
+ * @see {@link severity} for the annotation key used to override severity
+ * @see {@link Reportable} for the annotation properties recognized on object errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -229,6 +280,11 @@ export const getSeverity = error => {
  * Runtime property key used to attach extra key/value metadata to an object
  * error report.
  *
+ * **When to use**
+ *
+ * Use to attach domain metadata to object errors so reporter callbacks receive
+ * it with the reported failure.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.attributes]` to a record of metadata that should be
@@ -248,6 +304,12 @@ export const getSeverity = error => {
  * }
  * ```
  *
+ * @see {@link ignore} for suppressing reports for expected object errors
+ * @see {@link severity} for overriding reporter severity
+ * @see {@link getAttributes} for reading the metadata stored under this key
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -256,6 +318,24 @@ export const attributes = "~effect/ErrorReporter/attributes";
  * Reads the `ErrorReporter.attributes` annotation from an error object,
  * returning an empty record when unset.
  *
+ * **When to use**
+ *
+ * Use to inspect the attributes that reporter callbacks will receive for an
+ * object error.
+ *
+ * **Details**
+ *
+ * Returns the value stored under `ErrorReporter.attributes`, or the module's
+ * shared empty record when the annotation is absent.
+ *
+ * **Gotchas**
+ *
+ * The annotation value is returned as-is; this helper does not validate or
+ * clone it.
+ *
+ * @see {@link attributes} for the annotation key used to attach metadata
+ * @see {@link Reportable} for the annotation properties recognized on object errors
+ *
  * @category annotations
  * @since 4.0.0
  */

package/dist/ErrorReporter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorReporter.js","names":["Effect","effect","references","Layer","LogLevel","TypeId","make","report","reported","WeakSet","options","has","cause","add","i","reasons","length","reason","_tag","original","error","defect","isObject","isIgnored","pretty","causePrettyError","annotations","severity","getSeverity","attributes","getAttributes","emptyAttributes","CurrentErrorReporters","layer","reporters","withFiber","fnUntraced","fiber","currentReporters","Set","mergeWithExisting","getRef","reporter","isEffect","reportCauseUnsafe","void","ignore","u","values","includes"],"sources":["../src/ErrorReporter.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"ErrorReporter.js","names":["Effect","effect","references","Layer","LogLevel","TypeId","make","report","reported","WeakSet","options","has","cause","add","i","reasons","length","reason","_tag","original","error","defect","isObject","isIgnored","pretty","causePrettyError","annotations","severity","getSeverity","attributes","getAttributes","emptyAttributes","CurrentErrorReporters","layer","reporters","withFiber","fnUntraced","fiber","currentReporters","Set","mergeWithExisting","getRef","reporter","isEffect","reportCauseUnsafe","void","ignore","u","values","includes"],"sources":["../src/ErrorReporter.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/ExecutionPlan.d.ts

@@ -1,40 +1,84 @@
 /**
- * The `ExecutionPlan` module provides a way to describe ordered fallback
- * strategies for effects and streams that need different resources across
- * repeated attempts. An `ExecutionPlan` is a non-empty list of steps, where
- * each step supplies a `Context` or `Layer` and may control retries with an
- * attempt limit, a `Schedule`, or a `while` predicate.
+ * Defines finite fallback plans for effects and streams that should retry the
+ * same work with different services. An `ExecutionPlan` is a non-empty
+ * sequence of steps. Each step provides a `Context` or `Layer`, and can limit
+ * or shape retries with `attempts`, `schedule`, and `while`.
+ *
+ * Use a plan with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`.
+ * Those APIs run the wrapped work with the first step, retry within that step
+ * as directed, then move to later steps until the work succeeds or the plan is
+ * exhausted.
  *
  * **Mental model**
  *
- * - A plan is evaluated step by step until the wrapped effect or stream
- *   succeeds, or until every step has been exhausted
- * - Each step provides the services used while that step is active
- * - `attempts` limits how many times a step may be tried
- * - `schedule` controls retry timing and receives the failure input
- * - `while` can stop retrying a step based on the failure input
- * - `CurrentMetadata` exposes the current 1-based attempt and 0-based step
- *   index to code running under a plan
+ * - A step is a resource profile for one part of a fallback strategy
+ * - The active step supplies the services visible to the wrapped effect or
+ *   stream
+ * - `attempts` caps the number of tries for a step
+ * - `schedule` controls retry timing and receives the wrapped work's failure
+ *   value
+ * - `while` can stop the current step early by inspecting the same failure
+ *   value
+ * - `CurrentMetadata` exposes the 1-based attempt number and 0-based step
+ *   index to code running under the active step
  *
  * **Common tasks**
  *
  * - Build a plan with {@link make}
- * - Run an effect with a plan using `Effect.withExecutionPlan`
- * - Run a stream with a plan using `Stream.withExecutionPlan`
- * - Combine plans in order with {@link merge}
- * - Capture required services up front with `captureRequirements`
- * - Inspect the current attempt and step with {@link CurrentMetadata}
+ * - Append fallback plans with {@link merge}
+ * - Apply a plan with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`
+ * - Read active step and attempt information with {@link CurrentMetadata}
+ * - Carry the current environment into a plan with `captureRequirements`
+ *
+ * **Quickstart**
+ *
+ * **Example** (Retry with one layer, then fall back)
+ *
+ * ```ts
+ * import { Context, Effect, ExecutionPlan, Layer, Schedule } from "effect"
+ *
+ * class Endpoint extends Context.Service<Endpoint>()("Endpoint", {
+ *   make: Effect.succeed({ url: "primary" })
+ * }) {}
+ *
+ * const primary = Layer.succeed(Endpoint, Endpoint.of({ url: "primary" }))
+ * const fallback = Layer.succeed(Endpoint, Endpoint.of({ url: "fallback" }))
+ *
+ * const plan = ExecutionPlan.make(
+ *   {
+ *     provide: primary,
+ *     attempts: 2,
+ *     schedule: Schedule.recurs(1)
+ *   },
+ *   {
+ *     provide: fallback
+ *   }
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const endpoint = yield* Endpoint
+ *   if (endpoint.url === "primary") {
+ *     return yield* Effect.fail("unavailable")
+ *   }
+ *   return endpoint.url
+ * }).pipe(Effect.withExecutionPlan(plan))
+ * ```
  *
  * **Gotchas**
  *
  * - Plans must contain at least one step
  * - `attempts` must be greater than zero when provided
- * - If `attempts` is omitted, a step is attempted once unless a `schedule` is
- *   provided
- * - A `while` predicate returning `false` skips the remaining retries for that
- *   step and moves the plan forward
- * - Layer, schedule, and predicate requirements are tracked in the plan type
- *   until they are provided or captured
+ * - Without `attempts` or `schedule`, a step is tried once
+ * - A `schedule` can keep a step active until bounded by `attempts` or
+ *   stopped by `while`
+ * - Layer, schedule, and predicate requirements stay in the plan type until
+ *   they are provided or captured
+ *
+ * **See also**
+ *
+ * - {@link make} for constructing plans
+ * - {@link merge} for combining plans in order
+ * - {@link CurrentMetadata} for inspecting the active attempt
  *
  * @since 3.16.0
  */
@@ -64,6 +108,20 @@ export declare const TypeId: TypeId;
  * Returns `true` if a value is an `ExecutionPlan` by checking for the
  * `ExecutionPlan.TypeId` marker.
  *
+ * **When to use**
+ *
+ * Use when accepting an unknown value and you need to narrow it to an
+ * `ExecutionPlan` before reading plan fields or passing it to plan-consuming
+ * APIs.
+ *
+ * **Gotchas**
+ *
+ * This is a structural marker check; it does not validate the marker value or
+ * the shape of the plan steps.
+ *
+ * @see {@link make} for constructing execution plans that satisfy this guard
+ * @see {@link TypeId} for the runtime marker checked by this guard
+ *
  * @category guards
  * @since 3.16.0
  */
@@ -270,11 +328,18 @@ export declare namespace make {
 /**
  * Combines multiple execution plans by concatenating their steps in order.
  *
+ * **When to use**
+ *
+ * Use to combine separately defined fallback plans into one ordered plan before
+ * applying it to an effect or stream.
+ *
  * **Details**
  *
  * The resulting plan tries every step from the first plan, then every step from
  * the next plan, and so on.
  *
+ * @see {@link make} for building a plan from individual steps instead of combining existing plans
+ *
  * @category Combining
  * @since 3.16.0
  */

package/dist/ExecutionPlan.d.ts.map

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

package/dist/ExecutionPlan.js

@@ -16,6 +16,20 @@ export const TypeId = "~effect/ExecutionPlan";
  * Returns `true` if a value is an `ExecutionPlan` by checking for the
  * `ExecutionPlan.TypeId` marker.
  *
+ * **When to use**
+ *
+ * Use when accepting an unknown value and you need to narrow it to an
+ * `ExecutionPlan` before reading plan fields or passing it to plan-consuming
+ * APIs.
+ *
+ * **Gotchas**
+ *
+ * This is a structural marker check; it does not validate the marker value or
+ * the shape of the plan steps.
+ *
+ * @see {@link make} for constructing execution plans that satisfy this guard
+ * @see {@link TypeId} for the runtime marker checked by this guard
+ *
  * @category guards
  * @since 3.16.0
  */
@@ -100,11 +114,18 @@ const makeProto = steps => {
 /**
  * Combines multiple execution plans by concatenating their steps in order.
  *
+ * **When to use**
+ *
+ * Use to combine separately defined fallback plans into one ordered plan before
+ * applying it to an effect or stream.
+ *
  * **Details**
  *
  * The resulting plan tries every step from the first plan, then every step from
  * the next plan, and so on.
  *
+ * @see {@link make} for building a plan from individual steps instead of combining existing plans
+ *
  * @category Combining
  * @since 3.16.0
  */

package/dist/ExecutionPlan.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExecutionPlan.js","names":["Context","constant","effect","Layer","pipeArguments","Predicate","TypeId","isExecutionPlan","u","hasProperty","make","steps","makeProto","map","options","i","attempts","Error","schedule","while","input","suspend","result","succeed","undefined","provide","Proto","captureRequirements","self","contextWith","context","step","isLayer","succeedContext","pipe","arguments","Object","create","merge","plans","flatMap","plan","CurrentMetadata","Reference","defaultValue","attempt","stepIndex"],"sources":["../src/ExecutionPlan.ts"],"sourcesContent":[null],"mappings":"AAyCA,OAAO,KAAKA,OAAO,MAAM,cAAc;AAEvC,SAASC,QAAQ,QAAQ,eAAe;AACxC,OAAO,KAAKC,MAAM,MAAM,sBAAsB;AAC9C,OAAO,KAAKC,KAAK,MAAM,YAAY;AAEnC,SAASC,aAAa,QAAQ,eAAe;AAC7C,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAY3C;;;;;;;AAOA,OAAO,MAAMC,MAAM,GAAW,uBAAuB;AAErD;;;;;;;AAOA,OAAO,MAAMC,eAAe,GAAIC,CAAU,IAA8BH,SAAS,CAACI,WAAW,CAACD,CAAC,EAAEF,MAAM,CAAC;AAsGxG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,OAAO,MAAMI,IAAI,GAAGA,CAClB,GAAGC,KAAgD,KAanDC,SAAS,CAACD,KAAK,CAACE,GAAG,CAAC,CAACC,OAAO,EAAEC,CAAC,KAAI;EACjC,IAAID,OAAO,CAACE,QAAQ,IAAIF,OAAO,CAACE,QAAQ,GAAG,CAAC,EAAE;IAC5C,MAAM,IAAIC,KAAK,CAAC,4BAA4BF,CAAC,mCAAmC,CAAC;EACnF;EACA,OAAO;IACLG,QAAQ,EAAEJ,OAAO,CAACI,QAAQ;IAC1BF,QAAQ,EAAEF,OAAO,CAACE,QAAQ;IAC1BG,KAAK,EAAEL,OAAO,CAACK,KAAK,GACfC,KAAU,IACXlB,MAAM,CAACmB,OAAO,CAAC,MAAK;MAClB,MAAMC,MAAM,GAAGR,OAAO,CAACK,KAAM,CAACC,KAAK,CAAC;MACpC,OAAO,OAAOE,MAAM,KAAK,SAAS,GAAGpB,MAAM,CAACqB,OAAO,CAACD,MAAM,CAAC,GAAGA,MAAM;IACtE,CAAC,CAAC,GACFE,SAAS;IACbC,OAAO,EAAEX,OAAO,CAACW;GAClB;AACH,CAAC,CAAQ,CAAC;AAsFZ,MAAMC,KAAK,GAAsC;EAC/C,CAACpB,MAAM,GAAGA,MAAM;EAChB,IAAIqB,mBAAmBA,CAAA;IACrB,MAAMC,IAAI,GAAG,IAAiC;IAC9C,OAAO1B,MAAM,CAAC2B,WAAW,CAAEC,OAA6B,IACtD5B,MAAM,CAACqB,OAAO,CAACX,SAAS,CAACgB,IAAI,CAACjB,KAAK,CAACE,GAAG,CAAEkB,IAAI,KAAM;MACjD,GAAGA,IAAI;MACPN,OAAO,EAAEtB,KAAK,CAAC6B,OAAO,CAACD,IAAI,CAACN,OAAO,CAAC,GAChCtB,KAAK,CAACsB,OAAO,CAACM,IAAI,CAACN,OAAO,EAAEtB,KAAK,CAAC8B,cAAc,CAACH,OAAO,CAAC,CAAC,GAC1DC,IAAI,CAACN;KACV,CAAC,CAAQ,CAAC,CAAC,CACb;EACH,CAAC;EACDS,IAAIA,CAAA;IACF,OAAO9B,aAAa,CAAC,IAAI,EAAE+B,SAAS,CAAC;EACvC;CACD;AAED,MAAMvB,SAAS,GACbD,KAKW,IACT;EACF,MAAMiB,IAAI,GAAGQ,MAAM,CAACC,MAAM,CAACX,KAAK,CAAC;EACjCE,IAAI,CAACjB,KAAK,GAAGA,KAAK;EAClB,OAAOiB,IAAI;AACb,CAAC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMU,KAAK,GAAGA,CACnB,GAAGC,KAAY,KAMX3B,SAAS,CAAC2B,KAAK,CAACC,OAAO,CAAEC,IAAI,IAAKA,IAAI,CAAC9B,KAAK,CAAQ,CAAC;AAkB3D;;;;;;;AAOA,OAAO,MAAM+B,eAAe,gBAAG1C,OAAO,CAAC2C,SAAS,CAAW,sCAAsC,EAAE;EACjGC,YAAY,eAAE3C,QAAQ,CAAC;IACrB4C,OAAO,EAAE,CAAC;IACVC,SAAS,EAAE;GACZ;CACF,CAAC","ignoreList":[]}
+{"version":3,"file":"ExecutionPlan.js","names":["Context","constant","effect","Layer","pipeArguments","Predicate","TypeId","isExecutionPlan","u","hasProperty","make","steps","makeProto","map","options","i","attempts","Error","schedule","while","input","suspend","result","succeed","undefined","provide","Proto","captureRequirements","self","contextWith","context","step","isLayer","succeedContext","pipe","arguments","Object","create","merge","plans","flatMap","plan","CurrentMetadata","Reference","defaultValue","attempt","stepIndex"],"sources":["../src/ExecutionPlan.ts"],"sourcesContent":[null],"mappings":"AAqFA,OAAO,KAAKA,OAAO,MAAM,cAAc;AAEvC,SAASC,QAAQ,QAAQ,eAAe;AACxC,OAAO,KAAKC,MAAM,MAAM,sBAAsB;AAC9C,OAAO,KAAKC,KAAK,MAAM,YAAY;AAEnC,SAASC,aAAa,QAAQ,eAAe;AAC7C,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAY3C;;;;;;;AAOA,OAAO,MAAMC,MAAM,GAAW,uBAAuB;AAErD;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,eAAe,GAAIC,CAAU,IAA8BH,SAAS,CAACI,WAAW,CAACD,CAAC,EAAEF,MAAM,CAAC;AAsGxG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,OAAO,MAAMI,IAAI,GAAGA,CAClB,GAAGC,KAAgD,KAanDC,SAAS,CAACD,KAAK,CAACE,GAAG,CAAC,CAACC,OAAO,EAAEC,CAAC,KAAI;EACjC,IAAID,OAAO,CAACE,QAAQ,IAAIF,OAAO,CAACE,QAAQ,GAAG,CAAC,EAAE;IAC5C,MAAM,IAAIC,KAAK,CAAC,4BAA4BF,CAAC,mCAAmC,CAAC;EACnF;EACA,OAAO;IACLG,QAAQ,EAAEJ,OAAO,CAACI,QAAQ;IAC1BF,QAAQ,EAAEF,OAAO,CAACE,QAAQ;IAC1BG,KAAK,EAAEL,OAAO,CAACK,KAAK,GACfC,KAAU,IACXlB,MAAM,CAACmB,OAAO,CAAC,MAAK;MAClB,MAAMC,MAAM,GAAGR,OAAO,CAACK,KAAM,CAACC,KAAK,CAAC;MACpC,OAAO,OAAOE,MAAM,KAAK,SAAS,GAAGpB,MAAM,CAACqB,OAAO,CAACD,MAAM,CAAC,GAAGA,MAAM;IACtE,CAAC,CAAC,GACFE,SAAS;IACbC,OAAO,EAAEX,OAAO,CAACW;GAClB;AACH,CAAC,CAAQ,CAAC;AAsFZ,MAAMC,KAAK,GAAsC;EAC/C,CAACpB,MAAM,GAAGA,MAAM;EAChB,IAAIqB,mBAAmBA,CAAA;IACrB,MAAMC,IAAI,GAAG,IAAiC;IAC9C,OAAO1B,MAAM,CAAC2B,WAAW,CAAEC,OAA6B,IACtD5B,MAAM,CAACqB,OAAO,CAACX,SAAS,CAACgB,IAAI,CAACjB,KAAK,CAACE,GAAG,CAAEkB,IAAI,KAAM;MACjD,GAAGA,IAAI;MACPN,OAAO,EAAEtB,KAAK,CAAC6B,OAAO,CAACD,IAAI,CAACN,OAAO,CAAC,GAChCtB,KAAK,CAACsB,OAAO,CAACM,IAAI,CAACN,OAAO,EAAEtB,KAAK,CAAC8B,cAAc,CAACH,OAAO,CAAC,CAAC,GAC1DC,IAAI,CAACN;KACV,CAAC,CAAQ,CAAC,CAAC,CACb;EACH,CAAC;EACDS,IAAIA,CAAA;IACF,OAAO9B,aAAa,CAAC,IAAI,EAAE+B,SAAS,CAAC;EACvC;CACD;AAED,MAAMvB,SAAS,GACbD,KAKW,IACT;EACF,MAAMiB,IAAI,GAAGQ,MAAM,CAACC,MAAM,CAACX,KAAK,CAAC;EACjCE,IAAI,CAACjB,KAAK,GAAGA,KAAK;EAClB,OAAOiB,IAAI;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMU,KAAK,GAAGA,CACnB,GAAGC,KAAY,KAMX3B,SAAS,CAAC2B,KAAK,CAACC,OAAO,CAAEC,IAAI,IAAKA,IAAI,CAAC9B,KAAK,CAAQ,CAAC;AAkB3D;;;;;;;AAOA,OAAO,MAAM+B,eAAe,gBAAG1C,OAAO,CAAC2C,SAAS,CAAW,sCAAsC,EAAE;EACjGC,YAAY,eAAE3C,QAAQ,CAAC;IACrB4C,OAAO,EAAE,CAAC;IACVC,SAAS,EAAE;GACZ;CACF,CAAC","ignoreList":[]}