@proposit/proposit-core 2.3.1 → 2.4.1

package/dist/lib/conversation/conversation.js

@@ -0,0 +1,65 @@
+// Stateful conversation primitive for interactive, user-driven multi-turn
+// LLM exchanges.
+//
+// Holds the response-ID chain and cumulative token usage. The user
+// decides which turn runs next, in any amount and order, until a
+// terminal `finalize` turn ends it.
+//
+// A conversation is NOT a pipeline. It is a thin, builder-agnostic
+// stateful object that threads response-IDs and tallies tokens.
+import { executeTurn } from "./turn.js";
+/** Thrown when `.turn` is called on a closed conversation. */
+export class ConversationClosedError extends Error {
+    constructor() {
+        super("Conversation is closed — no more turns allowed.");
+        this.name = "ConversationClosedError";
+    }
+}
+// -- createConversation ----------------------------------------------------
+/**
+ * Create a new stateful conversation object.
+ *
+ * The conversation holds the response-ID chain and cumulative token
+ * usage. Each `.turn(...)` call executes a single stage through the
+ * conversation primitive's execution path, threading `previousResponseId`
+ * so the provider can chain against the upstream response.
+ */
+export function createConversation(deps) {
+    let closed = false;
+    let lastResponseId = null;
+    let cumulativeTokens = { input: 0, output: 0 };
+    return {
+        async turn(stage, input, opts) {
+            if (closed) {
+                throw new ConversationClosedError();
+            }
+            const turnInput = {
+                userMessage: input.userMessage,
+                previousResponseId: opts?.branchFrom ?? lastResponseId ?? undefined,
+            };
+            const result = await executeTurn(stage, turnInput, {
+                ...deps,
+                onComplete: opts?.onComplete,
+            });
+            lastResponseId = result.responseId;
+            cumulativeTokens = {
+                input: cumulativeTokens.input + result.tokenUsage.input,
+                output: cumulativeTokens.output + result.tokenUsage.output,
+            };
+            return result;
+        },
+        get lastResponseId() {
+            return lastResponseId;
+        },
+        get tokenUsage() {
+            return cumulativeTokens;
+        },
+        get closed() {
+            return closed;
+        },
+        close() {
+            closed = true;
+        },
+    };
+}
+//# sourceMappingURL=conversation.js.map

package/dist/lib/conversation/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../../src/lib/conversation/conversation.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,iBAAiB;AACjB,EAAE;AACF,mEAAmE;AACnE,iEAAiE;AACjE,oCAAoC;AACpC,EAAE;AACF,mEAAmE;AACnE,gEAAgE;AAKhE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAgCvC,8DAA8D;AAC9D,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAC9C;QACI,KAAK,CAAC,iDAAiD,CAAC,CAAA;QACxD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACzC,CAAC;CACJ;AAED,6EAA6E;AAE7E;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACrD,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,IAAI,cAAc,GAAuB,IAAI,CAAA;IAC7C,IAAI,gBAAgB,GAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAA;IAE9D,OAAO;QACH,KAAK,CAAC,IAAI,CACN,KAAmB,EACnB,KAAiB,EACjB,IAA4D;YAE5D,IAAI,MAAM,EAAE,CAAC;gBACT,MAAM,IAAI,uBAAuB,EAAE,CAAA;YACvC,CAAC;YAED,MAAM,SAAS,GAAe;gBAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,kBAAkB,EACd,IAAI,EAAE,UAAU,IAAI,cAAc,IAAI,SAAS;aACtD,CAAA;YAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE;gBAC/C,GAAG,IAAI;gBACP,UAAU,EAAE,IAAI,EAAE,UAAU;aAC/B,CAAC,CAAA;YAEF,cAAc,GAAG,MAAM,CAAC,UAAU,CAAA;YAClC,gBAAgB,GAAG;gBACf,KAAK,EAAE,gBAAgB,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK;gBACvD,MAAM,EAAE,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM;aAC7D,CAAA;YAED,OAAO,MAAM,CAAA;QACjB,CAAC;QAED,IAAI,cAAc;YACd,OAAO,cAAc,CAAA;QACzB,CAAC;QAED,IAAI,UAAU;YACV,OAAO,gBAAgB,CAAA;QAC3B,CAAC;QAED,IAAI,MAAM;YACN,OAAO,MAAM,CAAA;QACjB,CAAC;QAED,KAAK;YACD,MAAM,GAAG,IAAI,CAAA;QACjB,CAAC;KACJ,CAAA;AACL,CAAC"}

package/dist/lib/conversation/index.d.ts

@@ -0,0 +1,8 @@
+export { executeTurn } from "./turn.js";
+export type { TTurnInput, TTurnResult, TExecuteTurnDeps } from "./turn.js";
+export { createConversation } from "./conversation.js";
+export type { TConversation } from "./conversation.js";
+export { ConversationClosedError } from "./conversation.js";
+export type { TMultiTurnInput, TMultiTurnOutput } from "./contract.js";
+export type { TResponseId } from "../llm/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/conversation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/conversation/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACtE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/lib/conversation/index.js

@@ -0,0 +1,7 @@
+// Barrel export for the conversation primitive module.
+//
+// Subpath: @proposit/proposit-core/conversation
+export { executeTurn } from "./turn.js";
+export { createConversation } from "./conversation.js";
+export { ConversationClosedError } from "./conversation.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/conversation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/conversation/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,gDAAgD;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/lib/conversation/turn.d.ts

@@ -0,0 +1,55 @@
+import type { TStage, TProcessingFailure, TPipelineEvent } from "../pipelines/types.js";
+import type { TLlmProvider, TLlmTokenUsage, TResponseId } from "../llm/types.js";
+/**
+ * Input supplied to a single conversational turn. The caller is
+ * responsible for assembling the user message (which may include the
+ * full transcript when the provider cannot chain by reference).
+ */
+export type TTurnInput = {
+    /** The user message for this turn. */
+    userMessage: string;
+    /** The provider response id to chain against; absent for the first turn. */
+    previousResponseId?: TResponseId;
+};
+/**
+ * Result of a single conversational turn. Mirrors the shape the
+ * server's Argument Builder actions need: output, the new response id,
+ * token usage, and any processing failures.
+ */
+export type TTurnResult<TOut> = {
+    /** The stage's parsed output, or `null` when the turn failed. */
+    output: TOut | null;
+    /** The provider response id for this turn (nullable for
+     * non-chaining providers such as chat-completions). */
+    responseId: TResponseId | null;
+    /** Cumulative token usage for this turn's LLM call. */
+    tokenUsage: TLlmTokenUsage;
+    /** Processing failures recorded during the turn. */
+    failures: TProcessingFailure[];
+};
+/**
+ * Minimal dependencies for a single-turn execution. A subset of the
+ * full pipeline deps — no concurrency or pipeline-level bookkeeping.
+ */
+export type TExecuteTurnDeps = {
+    llm: TLlmProvider;
+    signal?: AbortSignal;
+    onEvent?: (event: TPipelineEvent) => void;
+    /** Called after the stage completes (after retry loop + validation).
+     * Useful for terminal turns that need to seal a conversation. */
+    onComplete?: () => void;
+};
+/**
+ * Run one conversational turn: execute the stage through the single-stage
+ * executor (preserving retry loop, output-schema validation, event
+ * emission, token accounting) while threading `previousResponseId` into
+ * the LLM request and surfacing the provider response id.
+ *
+ * Uses a synthetic pipeline so `executeStage` can run the arbitrary stage
+ * through the same execution machinery the full pipeline uses. The stage's
+ * own `dependsOn` are preserved; since no upstream stages exist, any
+ * dependencies that are satisfied will be `completed` (they simply don't
+ * exist, so `ctx.get` returns `undefined` for them).
+ */
+export declare function executeTurn<TOut>(stage: TStage<TOut>, input: TTurnInput, deps: TExecuteTurnDeps): Promise<TTurnResult<TOut>>;
+//# sourceMappingURL=turn.d.ts.map

package/dist/lib/conversation/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../src/lib/conversation/turn.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACR,MAAM,EACN,kBAAkB,EAClB,cAAc,EACjB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAShF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,WAAW,CAAA;CACnC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI;IAC5B,iEAAiE;IACjE,MAAM,EAAE,IAAI,GAAG,IAAI,CAAA;IACnB;2DACuD;IACvD,UAAU,EAAE,WAAW,GAAG,IAAI,CAAA;IAC9B,uDAAuD;IACvD,UAAU,EAAE,cAAc,CAAA;IAC1B,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,EAAE,CAAA;CACjC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC3B,GAAG,EAAE,YAAY,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC;qEACiE;IACjE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B,CAAA;AA+CD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAClC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,EACnB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,gBAAgB,GACvB,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CA6D5B"}

package/dist/lib/conversation/turn.js

@@ -0,0 +1,112 @@
+// Stateless single-turn execution primitive.
+//
+// Wraps one `TStage` run with the full pipeline machinery (retry loop,
+// output-schema validation, event emission, token accounting) and
+// threads `previousResponseId` into the LLM request so the provider can
+// chain against the upstream response. Surfaces the provider response id
+// so the caller can forward it on the next turn.
+//
+// This is the shared substrate for both:
+//   - the server's stateless per-request executor (threads the chain
+//     from the client-supplied `lastResponseId`)
+//   - the CLI's stateful conversation object (accumulates the chain)
+import { executeStage } from "../pipelines/single-stage.js";
+import { Value } from "typebox/value";
+import Type from "typebox";
+// -- Internal: module-level bridge for user message ------------------------
+//
+// `llmStage` builds its user message from `buildPrompt(ctx)`. To override
+// it without modifying the stage, we use a module-level variable that the
+// provider wrapper reads. This keeps `executeTurn`'s signature clean
+// while still letting the caller supply the actual user message.
+//
+// The variable is set synchronously before `executeStage` and cleared
+// after it resolves, so it's safe for sequential (non-concurrent) use.
+let currentTurnInput = null;
+// -- Internal: LLM provider wrapper ----------------------------------------
+//
+// Wraps the underlying provider to inject `previousResponseId` into each
+// `respond` call and capture the surfaced response id. Also overrides the
+// user message via the module-level bridge so `llmStage`'s `buildPrompt`
+// user message is replaced with the caller-supplied one.
+function wrapProviderForTurn(llm, previousResponseId, captured) {
+    const underlying = llm;
+    return {
+        async respond(req) {
+            // Inject `previousResponseId` into the request.
+            req.previousResponseId = previousResponseId;
+            // Override user message via the module-level bridge.
+            if (currentTurnInput) {
+                req.userMessage = currentTurnInput.userMessage;
+            }
+            const response = await underlying.respond(req);
+            // Capture the response id if surfaced.
+            if (response.rawResponseId) {
+                captured.responseId = response.rawResponseId;
+            }
+            return response;
+        },
+    };
+}
+// -- executeTurn -----------------------------------------------------------
+/**
+ * Run one conversational turn: execute the stage through the single-stage
+ * executor (preserving retry loop, output-schema validation, event
+ * emission, token accounting) while threading `previousResponseId` into
+ * the LLM request and surfacing the provider response id.
+ *
+ * Uses a synthetic pipeline so `executeStage` can run the arbitrary stage
+ * through the same execution machinery the full pipeline uses. The stage's
+ * own `dependsOn` are preserved; since no upstream stages exist, any
+ * dependencies that are satisfied will be `completed` (they simply don't
+ * exist, so `ctx.get` returns `undefined` for them).
+ */
+export async function executeTurn(stage, input, deps) {
+    // Capture the response id from the provider's response.
+    const captured = {
+        responseId: null,
+    };
+    // Wrap the LLM provider to inject `previousResponseId` and capture
+    // the response id.
+    const wrapped = wrapProviderForTurn(deps.llm, input.previousResponseId, captured);
+    // Bridge the user message to the provider wrapper.
+    currentTurnInput = input;
+    // Create a synthetic pipeline containing just this stage.
+    const stageId = stage.id;
+    const pipeline = {
+        id: "turn",
+        version: "0.0.0",
+        inputSchema: Value.Check(TypeAnySchema, {})
+            ? TypeAnySchema
+            : Type.Object({}),
+        outputSchema: stage.outputSchema,
+        stages: [stage],
+        finalize: {
+            dependsOn: [stageId],
+            run: (ctx) => ctx.get(stageId),
+        },
+    };
+    // Run the stage through the single-stage executor.
+    const upstream = {};
+    const result = await executeStage(pipeline, stageId, upstream, {}, {
+        llm: wrapped,
+        signal: deps.signal,
+        onEvent: deps.onEvent,
+    });
+    // Clear the user message bridge.
+    currentTurnInput = null;
+    // Call the completion callback (for terminal turns like finalize).
+    deps.onComplete?.();
+    return {
+        output: (result.outcome === "completed"
+            ? (result.output ?? null)
+            : null),
+        responseId: captured.responseId,
+        tokenUsage: result.tokenUsage ?? { input: 0, output: 0 },
+        failures: result.failures,
+    };
+}
+// -- Minimal `Type.Any()` without importing TypeBox ------------------------
+// Used as the synthetic pipeline's input schema.
+const TypeAnySchema = { type: "any" };
+//# sourceMappingURL=turn.js.map

package/dist/lib/conversation/turn.js.map

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

package/dist/lib/core/expression-manager-checks.d.ts

@@ -0,0 +1,73 @@
+import type { TCorePropositionalExpression } from "../schemata/index.js";
+import type { TCorePositionConfig } from "../utils/position.js";
+import type { TExpressionInput, TExpressionWithoutPosition, TExpressionUpdate } from "./expression-manager.js";
+/**
+ * Validates the preconditions for `ExpressionManager.insertExpression`
+ * (existence, arity, and root-only-operator rules) and returns the anchor
+ * slot the new expression inherits.
+ *
+ * @throws Under the same conditions documented on `insertExpression`.
+ */
+export declare function validateInsertExpression<TExpr extends TCorePropositionalExpression>(expression: TExpressionInput<TExpr>, leftNodeId: string | undefined, rightNodeId: string | undefined, expressions: Map<string, TExpr>): {
+    anchorParentId: string | null;
+    anchorPosition: number;
+};
+/**
+ * Validates the preconditions for `ExpressionManager.wrapExpression`
+ * (existence, arity, and root-only-operator rules) and returns the existing
+ * node's ID plus the anchor slot the operator inherits.
+ *
+ * @throws Under the same conditions documented on `wrapExpression`.
+ */
+export declare function validateWrapExpression<TExpr extends TCorePropositionalExpression>(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId: string | undefined, rightNodeId: string | undefined, expressions: Map<string, TExpr>): {
+    existingNodeId: string;
+    anchorParentId: string | null;
+    anchorPosition: number;
+};
+/**
+ * Computes the sibling-position redistribution range for
+ * `ExpressionManager.repositionSiblings`: which contiguous run of
+ * `children` to shift, and the bounds to spread them across.
+ *
+ * @throws If neither direction has enough space to redistribute into.
+ */
+export declare function validateRepositionSiblings<TExpr extends TCorePropositionalExpression>(children: TExpr[], leftPos: number, rightPos: number, positionConfig: TCorePositionConfig): {
+    startIdx: number;
+    endIdx: number;
+    lowerBound: number;
+    upperBound: number;
+    count: number;
+};
+/**
+ * Validates the preconditions for `ExpressionManager.updateExpression`
+ * and, when the update includes a position change, performs the sibling
+ * position-set swap (delete old position, reject or accept the new one).
+ *
+ * Mutates `childPositionsByParentId` in place when a position update is
+ * accepted — this is the one check in this module that isn't a pure
+ * throw-or-void helper, since the swap must happen atomically with the
+ * collision check to avoid leaving the position set inconsistent.
+ *
+ * @throws Under the same conditions documented on `updateExpression`.
+ */
+export declare function validateUpdateExpression<TExpr extends TCorePropositionalExpression>(expressionId: string, expression: TExpr, updates: TExpressionUpdate, childPositionsByParentId: Map<string | null, Set<number>>): void;
+/**
+ * Validates the preconditions for the single-child-promotion branch of
+ * `ExpressionManager.removeAndPromote` and returns which of the two
+ * branches applies.
+ *
+ * @throws If `target` has more than one child.
+ * @throws If the single child is a root-only operator (`implies`/`iff`)
+ *   that would be placed in a non-root position.
+ * @returns The child to promote, or `undefined` for a plain leaf removal.
+ */
+export declare function validateRemoveAndPromote<TExpr extends TCorePropositionalExpression>(expressionId: string, target: TExpr, children: TExpr[]): TExpr | undefined;
+/**
+ * Validates the preconditions for
+ * `ExpressionManager.addExpressionRelative` and returns the sibling
+ * looked up by ID.
+ *
+ * @throws If the sibling does not exist.
+ */
+export declare function validateAddExpressionRelative<TExpr extends TCorePropositionalExpression>(siblingId: string, expressions: Map<string, TExpr>): TExpr;
+//# sourceMappingURL=expression-manager-checks.d.ts.map

package/dist/lib/core/expression-manager-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-manager-checks.d.ts","sourceRoot":"","sources":["../../../src/lib/core/expression-manager-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAA;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,KAAK,EACR,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,EACpB,MAAM,yBAAyB,CAAA;AAShC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACpC,KAAK,SAAS,4BAA4B,EAE1C,UAAU,EAAE,gBAAgB,CAAC,KAAK,CAAC,EACnC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAChC;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CA6H3D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAClC,KAAK,SAAS,4BAA4B,EAE1C,QAAQ,EAAE,0BAA0B,CAAC,KAAK,CAAC,EAC3C,UAAU,EAAE,0BAA0B,CAAC,KAAK,CAAC,EAC7C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAChC;IACC,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,cAAc,EAAE,MAAM,CAAA;CACzB,CAmGA;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACtC,KAAK,SAAS,4BAA4B,EAE1C,QAAQ,EAAE,KAAK,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,mBAAmB,GACpC;IACC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CAChB,CAoFA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACpC,KAAK,SAAS,4BAA4B,EAE1C,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,KAAK,EACjB,OAAO,EAAE,iBAAiB,EAC1B,wBAAwB,EAAE,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAC1D,IAAI,CA0DN;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACpC,KAAK,SAAS,4BAA4B,EAC5C,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,SAAS,CAgC3E;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CACzC,KAAK,SAAS,4BAA4B,EAC5C,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAM3D"}