@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Steering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Steering.js","sourceRoot":"","sources":["../../src/Steering.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Turn-boundary steering values and their source contract.\n *\n * Governing design: `../docs/concepts.md#notification-queue`.\n *\n * @since 0.1.0\n */\n\nimport * as ModelRequest from \"@smthrs/model/ModelRequest\"\nimport { Context, Effect, Layer, Schema } from \"effect\"\nimport * as AgentEvent from \"./AgentEvent.ts\"\nimport type { HarnessError } from \"./HarnessError.ts\"\nimport * as compactionMarks from \"./internal/compactionMarks.ts\"\nimport * as Monitor from \"./Monitor.ts\"\n\n/**\n * The boundary at which a transcript insertion may be promoted.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport type Delivery = \"steer\" | \"queue\"\n\n/**\n * A transcript insertion promoted at the next turn boundary.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface SteerInsert {\n  readonly _tag: \"Insert\"\n  readonly delivery: \"steer\"\n  readonly admittedAt: number\n  readonly message: ModelRequest.Message\n}\n\n/**\n * A transcript insertion promoted only when the run would otherwise go idle.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface QueueInsert {\n  readonly _tag: \"Insert\"\n  readonly delivery: \"queue\"\n  readonly admittedAt: number\n  readonly message: ModelRequest.Message\n}\n\n/**\n * A transcript insertion admitted for a future turn.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport type Insert = SteerInsert | QueueInsert\n\n/**\n * A model-seat change that applies only after the current turn closes.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface SeatChange {\n  readonly _tag: \"SeatChange\"\n  readonly delivery: \"steer\"\n  readonly admittedAt: number\n  readonly seat: string\n}\n\n/**\n * A thinking-level change that applies only after the current turn closes.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface ThinkingChange {\n  readonly _tag: \"ThinkingChange\"\n  readonly delivery: \"steer\"\n  readonly admittedAt: number\n  readonly thinking: ModelRequest.ReasoningEffort\n}\n\n/**\n * A serializable steering event.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport type Item = Insert | SeatChange | ThinkingChange\n\n/**\n * An immutable, FIFO queue of steering events.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface Queue {\n  readonly items: ReadonlyArray<Item>\n}\n\n/**\n * The values promoted when a turn reaches its close boundary.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface Drain {\n  readonly inserts: ReadonlyArray<ModelRequest.Message>\n  readonly seatChanges: ReadonlyArray<SeatChange | ThinkingChange>\n  readonly remaining: Queue\n  readonly queued: boolean\n  /**\n   * Whether this boundary had already drained, so the answer is the one it gave\n   * the first time.\n   *\n   * This is what makes a parked run answerable. A park resumes by re-executing\n   * its own frames, so it reaches the same boundary again and must be told the\n   * same thing — and it must also be able to find out that a NEWER boundary is\n   * the one an operator's answer is waiting at. A run walks its park's\n   * boundaries until one reports `false`, which is the first one this run has\n   * not consulted before.\n   *\n   * Host queue bookkeeping, like {@link Drain.remaining}, and deliberately not\n   * part of {@link DrainRecord}: it says which attempt asked, not what the\n   * boundary holds, and freezing it in a journaled value would tell every later\n   * attempt it was the first.\n   */\n  readonly duplicate: boolean\n}\n\n/**\n * The boundary a drain is being attempted at, and whether the run would go\n * idle if nothing were delivered. Followups are held back until it would.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface BoundaryInput {\n  readonly boundary: string\n  readonly wouldIdle: boolean\n  /**\n   * Set only at an honored park's boundary: why the run parked and what it\n   * asked. A source that can reach a person may show them the question and\n   * answer the drain with their reply; one that cannot ignores it.\n   */\n  readonly park?: {\n    readonly reason: \"waiting-input\" | \"waiting-event\" | \"waiting-quota\"\n    readonly message: string\n  } | undefined\n}\n\nconst SeatChangeRecord = Schema.Struct({\n  _tag: Schema.Literal(\"SeatChange\"),\n  delivery: Schema.Literal(\"steer\"),\n  admittedAt: Schema.Number,\n  seat: Schema.String\n})\n\nconst ThinkingChangeRecord = Schema.Struct({\n  _tag: Schema.Literal(\"ThinkingChange\"),\n  delivery: Schema.Literal(\"steer\"),\n  admittedAt: Schema.Number,\n  thinking: ModelRequest.ReasoningEffort\n})\n\n/**\n * The journaled record of one turn-boundary drain.\n *\n * A drain consumes host queue state, so it is a nondeterministic read: the\n * controller journals exactly this projection through `EngineLike.record`,\n * keyed on the frame and boundary, and a re-executed frame replays the record\n * instead of draining an already-drained queue. Everything the controller\n * folds into durable state is here; `remaining` is host queue bookkeeping and\n * deliberately is not.\n *\n * @category schemas\n * @since 0.1.0\n * @slop\n */\nexport const DrainRecord = Schema.Struct({\n  inserts: Schema.Array(ModelRequest.Message),\n  seatChanges: Schema.Array(Schema.Union([SeatChangeRecord, ThinkingChangeRecord])),\n  queued: Schema.Boolean,\n  /**\n   * Messages the run's supervisor delivers at this boundary, kept apart from\n   * `inserts` because they are not the person's words: the model reads them,\n   * and the completion brake's task never does. Absent from records written\n   * before the supervisor had a field of its own, and from boundaries it\n   * delivered nothing at.\n   */\n  supervisor: Schema.optional(Schema.Array(ModelRequest.Message)),\n  /**\n   * Keys of the memory rows among `supervisor`, which the run has now been\n   * shown. Absent from boundaries that delivered none.\n   */\n  memory: Schema.optional(Schema.Array(Schema.String)),\n  /** The monitor whose message leads `supervisor`, when one was delivered. */\n  monitor: Schema.optional(Schema.String),\n  /** Crossed monitors this boundary withheld, and why. Absent when none was. */\n  suppressed: Schema.optional(Schema.Array(Schema.Struct({ id: Schema.String, reason: AgentEvent.Suppression }))),\n  /**\n   * The monitor ledger after this boundary gated a reading, which the run\n   * carries into its next frame. Absent from boundaries that gated none.\n   */\n  monitorLedger: Schema.optional(Monitor.Ledger),\n  /**\n   * Jev's answers about transcript segments, by digest, which the run stores\n   * for its next compaction. The model is not sent them. Absent from\n   * boundaries that took none.\n   */\n  marks: Schema.optional(Schema.Array(compactionMarks.Marking)),\n  /**\n   * The context triggers the delivered supervisor reading fired, which\n   * compact the run at its next frame. Absent from boundaries that took none.\n   */\n  compact: Schema.optional(Schema.Array(AgentEvent.CompactionCause))\n})\n\n/**\n * The journaled record of one turn-boundary drain.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport type DrainRecord = typeof DrainRecord.Type\n\n/**\n * Projects a {@link Drain} into its journaled record.\n *\n * @category conversions\n * @since 0.1.0\n * @slop\n */\nexport const drainRecord = (drain: Drain): DrainRecord => ({\n  inserts: drain.inserts,\n  seatChanges: drain.seatChanges,\n  queued: drain.queued\n})\n\nconst immutable = (items: ReadonlyArray<Item>): Queue => Object.freeze({ items: Object.freeze([...items]) })\n\nconst immutableItem = (item: Item): Item => Object.freeze({ ...item })\n\n/**\n * Creates an empty immutable steering queue.\n *\n * @category constructors\n * @since 0.1.0\n * @slop\n */\nexport const empty = (): Queue => immutable([])\n\n/**\n * Appends an item without mutating the prior queue.\n *\n * @category operations\n * @since 0.1.0\n * @slop\n */\nexport const enqueue = (queue: Queue, item: Item): Queue => immutable([...queue.items, immutableItem(item)])\n\n/**\n * Drains only items admitted at or before the turn's fixed cutoff.\n *\n * @category operations\n * @since 0.1.0\n * @slop\n */\nexport const drainAtClose = (queue: Queue, cutoff: number): Drain => {\n  const inserts: Array<ModelRequest.Message> = []\n  const seatChanges: Array<SeatChange | ThinkingChange> = []\n  const remaining: Array<Item> = []\n  for (const item of queue.items) {\n    if (item.delivery === \"queue\" || item.admittedAt > cutoff) {\n      remaining.push(item)\n      continue\n    }\n    switch (item._tag) {\n      case \"Insert\":\n        inserts.push(item.message)\n        break\n      case \"SeatChange\":\n      case \"ThinkingChange\":\n        seatChanges.push(item)\n        break\n    }\n  }\n  return {\n    inserts: Object.freeze(inserts),\n    seatChanges: Object.freeze(seatChanges),\n    remaining: immutable(remaining),\n    queued: false,\n    // An in-memory cutoff drain keeps no boundary ledger, so it can never say\n    // it has answered this boundary before.\n    duplicate: false\n  }\n}\n\n/**\n * Source of a serializable steering-queue snapshot. Storage and persistence\n * promotion are deliberately supplied by the host.\n *\n * @category services\n * @since 0.1.0\n * @slop\n */\nexport interface Source {\n  readonly read: () => Effect.Effect<Queue, HarnessError>\n  /**\n   * Promotes what one boundary may deliver.\n   *\n   * A drain is IDEMPOTENT in its boundary string: a second drain at one\n   * boundary promotes nothing and hands back exactly what the first one\n   * promoted, with {@link Drain.duplicate} set. That is not an optimization, it\n   * is the contract a resumed run depends on — a re-executed frame drains the\n   * boundaries it already drained and must be told the same thing, or it\n   * rebuilds a different context and re-keys every later sealed step. A source\n   * that promotes afresh each time cannot answer a parked run and will deliver\n   * one message many times.\n   */\n  readonly drain: (input: BoundaryInput) => Effect.Effect<Drain, HarnessError>\n}\n\n/**\n * The methods {@link make} needs to build a {@link Source}.\n *\n * @category models\n * @since 0.1.0\n * @slop\n */\nexport interface SourceInput {\n  readonly read: () => Effect.Effect<Queue, HarnessError>\n  readonly drain: (input: BoundaryInput) => Effect.Effect<Drain, HarnessError>\n}\n\n/**\n * Service tag for the external steering queue source.\n *\n * @category services\n * @since 0.1.0\n * @slop\n */\nexport const Source: Context.Service<Source, Source> = Context.Service(\"@smthrs/harness/Steering/Source\")\n\n/**\n * Constructs a steering source service.\n *\n * @category constructors\n * @since 0.1.0\n * @slop\n */\nexport const make = (implementation: SourceInput): Source => Source.of(implementation)\n\n/**\n * Creates a source that always returns an empty queue.\n *\n * @category constructors\n * @since 0.1.0\n * @slop\n */\nexport const makeNoop = (overrides: Partial<Source> = {}): Source =>\n  make({\n    read: Effect.fn(\"Steering.Source.read\")(() => Effect.succeed(empty())),\n    drain: Effect.fn(\"Steering.Source.drain\")(() =>\n      Effect.succeed({\n        inserts: [],\n        seatChanges: [],\n        remaining: empty(),\n        queued: false,\n        duplicate: false\n      })\n    ),\n    ...overrides\n  })\n\n/**\n * Provides a steering source as a layer.\n *\n * @category layers\n * @since 0.1.0\n * @slop\n */\nexport const layer = (implementation: SourceInput): Layer.Layer<Source> => Layer.succeed(Source)(make(implementation))\n\n/**\n * Provides an empty steering source as a layer.\n *\n * @category layers\n * @since 0.1.0\n * @slop\n */\nexport const layerNoop = (overrides: Partial<Source> = {}): Layer.Layer<Source> =>\n  Layer.succeed(Source)(makeNoop(overrides))\n"]}

package/dist/esm/StructuredOutput.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Turning one agent's final text into a value the declared output schema
+ * accepts, or into a typed failure.
+ *
+ * A model may answer with a bare JSON document, prose wrapped around a JSON
+ * document, a fenced block, or JSON of the wrong shape. Downstream nodes must
+ * never receive that ambiguity, so this module implements the recovery
+ * contract in `../docs/concepts.md#structured-output`:
+ *
+ * 1. parse the complete, BOM-stripped response and decode it;
+ * 2. otherwise scan once for balanced JSON containers, take the container
+ *    whose matching close ends last, and decode that;
+ * 3. otherwise report a typed {@link StructuredOutputFailure} carrying bounded
+ *    diagnostics, which is what a caller re-prompts with when it still holds a
+ *    correction slot.
+ *
+ * Every candidate is decoded by the declared schema. Extraction never relaxes
+ * validation: it only decides which bytes are offered to it, and the schema may
+ * accept any JSON root rather than silently requiring an object.
+ *
+ * The prompt half is {@link instructions}. It renders the declared schema as a
+ * JSON Schema document placed in the run's system teaching, which is BAML's
+ * `ctx.output_format` injection reached through the seam the vault note
+ * specifies — the model is told the shape before it answers, and the answer is
+ * still validated locally. Provider acceptance is not a cast.
+ *
+ * Reference consulted: the `generateObject` function from Effect's
+ * `effect/unstable/ai/LanguageModel` module, which
+ * sends `responseFormat: { type: "json", schema }` and then decodes the result
+ * with the same schema, failing `AiError.InvalidOutputError` on mismatch. The
+ * decode-and-fail-typed half is copied. The provider `responseFormat` half is
+ * not reachable here: `@smthrs/model`'s `ModelRequest.GenerationParams` has no
+ * response-format field, and the cell loop's final answer is a `Cell.Complete`
+ * `output` string rather than a provider-decoded value, so the schema is
+ * carried in the prompt and enforced at this boundary.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * Stable reasons a structured-output boundary failed.
+ *
+ * `invalid_json` means candidate text was not JSON. `schema_mismatch` means
+ * JSON parsed but the declared schema refused it. `no_candidate` means the
+ * answer contained no candidate text. `correction_exhausted` means the
+ * boundary had already spent its correction budget.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const StructuredOutputFailureCode: Schema.Literals<readonly ["invalid_json", "schema_mismatch", "no_candidate", "correction_exhausted"]>;
+/**
+ * Stable reasons a structured-output boundary failed.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export type StructuredOutputFailureCode = typeof StructuredOutputFailureCode.Type;
+/**
+ * Stable reasons an individual structured-output issue was reported.
+ *
+ * `invalid_json` means candidate text was not JSON. `no_candidate` means the
+ * answer contained no candidate text. `invalid_type` means a decoded value had
+ * the wrong type. `invalid_value` means a value of the expected type was still
+ * invalid. `missing_key` means a required property was absent.
+ * `unexpected_key` means a prohibited extra property was present. `forbidden`
+ * means decoding attempted an operation the schema forbids. `one_of` means
+ * more than one exclusive union member matched. `constraint` means a schema
+ * check or empty-union fallback failed.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const OutputIssueCode: Schema.Literals<readonly ["invalid_json", "no_candidate", "invalid_type", "invalid_value", "missing_key", "unexpected_key", "forbidden", "one_of", "constraint"]>;
+/**
+ * Stable reasons an individual structured-output issue was reported.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export type OutputIssueCode = typeof OutputIssueCode.Type;
+declare const OutputIssue_base: Schema.Class<OutputIssue, Schema.Struct<{
+    /** The stable reason this issue was reported. */
+    readonly code: Schema.Literals<readonly ["invalid_json", "no_candidate", "invalid_type", "invalid_value", "missing_key", "unexpected_key", "forbidden", "one_of", "constraint"]>;
+    /** The JSON path of the offending value, dot/bracket joined; empty for the root. */
+    readonly path: Schema.String;
+    /** What the decoder wanted there. */
+    readonly message: Schema.String;
+}>, {}>;
+/**
+ * One bounded issue raised while decoding structured output.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare class OutputIssue extends OutputIssue_base {
+    /** Renders the issue for existing prose-oriented consumers. */
+    toString(): string;
+}
+declare const StructuredOutputFailure_base: Schema.Class<StructuredOutputFailure, Schema.TaggedStruct<"/harness/StructuredOutputFailure", {
+    /** The stable reason this boundary failed. */
+    readonly code: Schema.Literals<readonly ["invalid_json", "schema_mismatch", "no_candidate", "correction_exhausted"]>;
+    /** The declared output schema's canonical digest. */
+    readonly schema: Schema.String;
+    /** SHA-256 of the text the decoder was last offered. */
+    readonly candidate: Schema.String;
+    /** Correction attempts already spent on this boundary. */
+    readonly corrections: Schema.Number;
+    /** The correction budget the boundary was declared with. */
+    readonly limit: Schema.Number;
+    /** At most {@link maxIssues} structured validation issues. */
+    readonly issues: Schema.$Array<typeof OutputIssue>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The terminal failure of one structured-output boundary.
+ *
+ * It carries what an operator needs to tell two identical-looking refusals
+ * apart: which schema was demanded, how many correction slots the attempt
+ * consumed out of its budget, the digest of the last candidate that was
+ * offered to the decoder, and the bounded issue list.
+ *
+ * @category errors
+ * @since 0.1.0
+ * @slop
+ */
+export declare class StructuredOutputFailure extends StructuredOutputFailure_base {
+}
+/**
+ * The most validation issues a failure or a correction prompt carries.
+ *
+ * Bounded for the same reason smithers bounds its own validation summary: a
+ * wide struct that mismatched everywhere would otherwise spend the correction
+ * prompt's whole budget restating the schema back to the model.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const maxIssues = 5;
+/**
+ * The JSON Schema document for a declared output schema.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const jsonSchema: (schema: Schema.Top) => unknown;
+/**
+ * The canonical digest of a declared output schema.
+ *
+ * Two declarations that render the same JSON Schema name the same boundary, so
+ * this is what a step key folds in rather than the schema value itself.
+ *
+ * @category identity
+ * @since 0.1.0
+ * @slop
+ */
+export declare const digest: (schema: Schema.Top) => string;
+/**
+ * The system teaching that tells a run what its final `output` must be.
+ *
+ * Written against the cell contract: a cell finishes by calling
+ * `ctx.done(output)`, and the sandbox rejects a returned transition, so the
+ * instruction is about the argument of that call and not about the assistant
+ * message around it. The run passes the value itself: a structured value
+ * reaches {@link decode} as canonical JSON, and a string as its own text.
+ *
+ * @category prompts
+ * @since 0.1.0
+ * @slop
+ */
+export declare const instructions: (schema: Schema.Top) => string;
+/**
+ * The digest of one failure's rendered validation issues.
+ *
+ * Two rejections that raised the same issues share this digest, which is what a
+ * record carries instead of the issues themselves: a journal that repeated the
+ * validator's prose for every correction would grow with the model's verbosity,
+ * and what an operator actually asks is whether the second answer was wrong the
+ * same way as the first.
+ *
+ * @category identity
+ * @since 0.1.0
+ */
+export declare const issuesDigest: (failure: StructuredOutputFailure) => string;
+/**
+ * The correction teaching appended when a candidate failed to decode.
+ *
+ * It restates the schema and the bounded diagnostics and nothing else: a
+ * correction does not reinterpret the task, so the original prompt is repeated
+ * verbatim by the caller and only this section is new.
+ *
+ * @category prompts
+ * @since 0.1.0
+ * @slop
+ */
+export declare const correction: (failure: StructuredOutputFailure) => string;
+/**
+ * The balanced JSON container whose matching close ends last.
+ *
+ * Scans once, left to right, tracking object and array delimiters, quoted
+ * strings, and escapes. A mismatched close abandons the open container rather
+ * than pairing it with the wrong opener, so a truncated prefix cannot be
+ * reported as a complete document. `undefined` means the text holds no
+ * balanced container at all.
+ *
+ * This is the array-capable form of smithers' `extractLastBalancedJson`, which
+ * is object-only.
+ *
+ * @category extraction
+ * @since 0.1.0
+ * @slop
+ */
+export declare const lastBalanced: (text: string) => string | undefined;
+/**
+ * The candidates offered to the decoder, in the declared recovery order.
+ *
+ * @category extraction
+ * @since 0.1.0
+ * @slop
+ */
+export declare const candidates: (text: string) => ReadonlyArray<string>;
+/**
+ * Decodes one agent answer with the declared output schema.
+ *
+ * Decodes an original completion value first when supplied. Only a string
+ * refused for its type proceeds to legacy text extraction; refinements and
+ * nonstring failures retain the original value's diagnostics.
+ * Tries every {@link candidates} entry in order and returns the first the
+ * schema accepts, then the answer itself, untrimmed, as a string unless it is
+ * a JSON string literal, which is how a `ctx.done("text")` answer reaches a
+ * string schema. When none does, the failure reports the issues raised by the
+ * LAST candidate, which is the narrowest text the extractor could isolate and
+ * therefore the one a correction prompt should be about.
+ *
+ * @category decoding
+ * @since 0.1.0
+ * @slop
+ */
+export declare const decode: <S extends Schema.Top>(schema: S, text: string, attempt: {
+    readonly corrections: number;
+    readonly limit: number;
+}, value?: Schema.Json | undefined) => Effect.Effect<S["Type"], StructuredOutputFailure, S["DecodingServices"]>;
+export {};
+//# sourceMappingURL=StructuredOutput.d.ts.map

package/dist/esm/StructuredOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StructuredOutput.d.ts","sourceRoot":"","sources":["../../src/StructuredOutput.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,uGAKtC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,2BAA2B,GAAG,OAAO,2BAA2B,CAAC,IAAI,CAAA;AAEjF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,mKAU1B,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;;IAUvD,iDAAiD;;IAEjD,oFAAoF;;IAEpF,qCAAqC;;;AAZvC;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,gBAO/B;IACA,+DAA+D;IACtD,QAAQ,IAAI,MAAM;CAG5B;;IAiBG,8CAA8C;;IAE9C,qDAAqD;;IAErD,wDAAwD;;IAExD,0DAA0D;;IAE1D,4DAA4D;;IAE5D,8DAA8D;;;;AAzBlE;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAwB,SAAQ,4BAiB5C;CAAG;AAIJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,IAAI,CAAA;AAE1B;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,CAAC,GAAG,KAAG,OAK/C,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,MAAM,CAAC,GAAG,KAAG,MAA6D,CAAA;AAEzG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,CAAC,GAAG,KAAG,MAS3C,CAAA;AAEP;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,uBAAuB,KAAG,MAG7D,CAAA;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,uBAAuB,KAAG,MAQJ,CAAA;AAI1D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAqCpD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,aAAa,CAAC,MAAM,CAI7D,CAAA;AAqDD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,CAAC,GAAG,EACzC,QAAQ,CAAC,EACT,MAAM,MAAM,EACZ,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACjE,QAAQ,MAAM,CAAC,IAAI,GAAG,SAAS,KAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,EAAE,CAAC,CAAC,kBAAkB,CAAC,CA0EtE,CAAA"}