loopforge 1.15.1 → 2.0.1

package/dist/round-transaction.js

@@ -0,0 +1,290 @@
+/** Schema-versioned round transaction shared by Runtime and MCP.
+ *
+ * A logical round has one deterministic roundId. Rejected attempts keep the
+ * same identity and before snapshot; only accepted decisions are committed to
+ * feedback storage. The committed feedback embeds the decision so replay after
+ * a process crash is idempotent.
+ */
+import { diffSnapshotCollections, extractFilesFromSnapshots, } from "./evidence-provider.js";
+import { RoundCoordinator, } from "./round-coordinator.js";
+import { logEvent, startSpan } from "./observability.js";
+import { policyMetrics } from "./policy-metrics.js";
+import { VaultRoundCommitStore } from "./storage.js";
+export const ROUND_TRANSACTION_SCHEMA_VERSION = 1;
+export function makeRoundId(loopId, round) {
+    if (!Number.isInteger(round) || round < 1) {
+        throw new Error(`Invalid round number: ${round}`);
+    }
+    return `loop:${loopId}:round:${round}`;
+}
+export function prepareRoundTransaction(loopId, round, beforeEvidence, promptArtifact) {
+    const now = Date.now();
+    return {
+        schemaVersion: ROUND_TRANSACTION_SCHEMA_VERSION,
+        roundId: makeRoundId(loopId, round),
+        loopId,
+        round,
+        attempt: 1,
+        phase: promptArtifact ? "prompted" : "prepared",
+        beforeEvidence,
+        createdAt: now,
+        updatedAt: now,
+        promptArtifact,
+    };
+}
+/** Attach the next prompt attempt to a rejected logical round without changing
+ * its identity or evidence baseline. Evaluation fields belong to the previous
+ * attempt and are cleared before the Agent receives the retry prompt. */
+export function prepareRejectedAttempt(rejected, promptArtifact) {
+    if (rejected.phase !== "rejected") {
+        throw new Error(`Cannot retry transaction in phase ${rejected.phase}`);
+    }
+    if (promptArtifact.roundId !== rejected.roundId) {
+        throw new Error(`Retry prompt identity mismatch: ${promptArtifact.roundId} !== ${rejected.roundId}`);
+    }
+    if (promptArtifact.attempt !== rejected.attempt + 1) {
+        throw new Error(`Retry prompt attempt mismatch: ${promptArtifact.attempt} !== ${rejected.attempt + 1}`);
+    }
+    return {
+        ...rejected,
+        attempt: promptArtifact.attempt,
+        phase: "prompted",
+        afterEvidence: undefined,
+        roundEvidence: undefined,
+        evaluation: undefined,
+        result: undefined,
+        promptArtifact,
+        updatedAt: Date.now(),
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isProcessResult(value) {
+    if (!isRecord(value))
+        return false;
+    return ["continue", "stop", "reject", "terminate"].includes(String(value.action)) && Array.isArray(value.verificationFlags);
+}
+function parseProviderSnapshots(value) {
+    if (!Array.isArray(value))
+        return null;
+    const snapshots = [];
+    for (const item of value) {
+        if (!isRecord(item))
+            return null;
+        if (typeof item.provider !== "string" ||
+            typeof item.timestamp !== "number" ||
+            !Array.isArray(item.files) ||
+            !item.files.every((file) => typeof file === "string") ||
+            !isRecord(item.data))
+            return null;
+        snapshots.push(item);
+    }
+    return snapshots;
+}
+/** Parse a persisted snapshot without trusting arbitrary vault data. */
+export function parseRoundTransactionSnapshot(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.schemaVersion !== ROUND_TRANSACTION_SCHEMA_VERSION)
+        return null;
+    if (typeof value.roundId !== "string" || typeof value.loopId !== "string") {
+        return null;
+    }
+    if (!Number.isInteger(value.round) || value.round < 1)
+        return null;
+    if (!Number.isInteger(value.attempt) || value.attempt < 1)
+        return null;
+    if (!["prepared", "prompted", "evaluated", "rejected", "committed", "terminated"]
+        .includes(String(value.phase)))
+        return null;
+    const beforeEvidence = parseProviderSnapshots(value.beforeEvidence);
+    if (!beforeEvidence)
+        return null;
+    const afterEvidence = value.afterEvidence === undefined
+        ? undefined
+        : parseProviderSnapshots(value.afterEvidence);
+    if (value.afterEvidence !== undefined && !afterEvidence)
+        return null;
+    const roundEvidence = value.roundEvidence === undefined
+        ? undefined
+        : parseProviderSnapshots(value.roundEvidence);
+    if (value.roundEvidence !== undefined && !roundEvidence)
+        return null;
+    if (value.result !== undefined && !isProcessResult(value.result))
+        return null;
+    if (value.promptArtifact !== undefined) {
+        if (!isRecord(value.promptArtifact))
+            return null;
+        const artifact = value.promptArtifact;
+        if (artifact.schemaVersion !== 1 ||
+            typeof artifact.roundId !== "string" ||
+            typeof artifact.renderedPrompt !== "string" ||
+            typeof artifact.promptHash !== "string" ||
+            typeof artifact.stateHash !== "string" ||
+            !["l0", "l1", "l2"].includes(String(artifact.level)))
+            return null;
+    }
+    const snapshot = {
+        ...value,
+        beforeEvidence,
+        afterEvidence,
+        roundEvidence,
+    };
+    if (snapshot.roundId !== makeRoundId(snapshot.loopId, snapshot.round)) {
+        return null;
+    }
+    return snapshot;
+}
+export class RoundTransactionCoordinator {
+    engine;
+    backend;
+    commitStore;
+    constructor(engine, backend, commitStore) {
+        this.engine = engine;
+        this.backend = backend ?? engine.getBackend();
+        this.commitStore = commitStore ?? new VaultRoundCommitStore(this.backend);
+    }
+    process(input) {
+        const { snapshot } = input;
+        const span = startSpan("round.transaction", {
+            loopId: snapshot.loopId,
+            round: snapshot.round,
+            roundId: snapshot.roundId,
+            attempt: snapshot.attempt,
+        });
+        const finish = (outcome) => {
+            policyMetrics.recordRound(snapshot.loopId, outcome.result, outcome.replayed);
+            span.end("ok", {
+                action: outcome.result.action,
+                replayed: outcome.replayed,
+                phase: outcome.snapshot.phase,
+            });
+            return outcome;
+        };
+        try {
+            const expectedRoundId = makeRoundId(snapshot.loopId, snapshot.round);
+            if (snapshot.roundId !== expectedRoundId) {
+                throw new Error(`Round snapshot identity mismatch: ${snapshot.roundId} !== ${expectedRoundId}`);
+            }
+            const committed = this.readCommitted(snapshot);
+            if (committed) {
+                logEvent("round_transaction_replay", {
+                    loopId: snapshot.loopId,
+                    round: snapshot.round,
+                    roundId: snapshot.roundId,
+                });
+                return finish(committed);
+            }
+            const attempt = snapshot.phase === "rejected"
+                ? snapshot.attempt + 1
+                : snapshot.attempt;
+            const roundEvidence = diffSnapshotCollections(snapshot.beforeEvidence, input.actualEvidence);
+            const coordinator = new RoundCoordinator(this.backend);
+            const result = coordinator.processRound({
+                loopId: snapshot.loopId,
+                task: input.task,
+                currentRound: snapshot.round,
+                maxRounds: input.maxRounds,
+                selfEval: input.selfEval,
+                extractionSucceeded: input.extractionSucceeded,
+                lastSelfEval: input.lastSelfEval,
+                consecutiveRejections: input.consecutiveRejections,
+                runtimeFilesChanged: extractFilesFromSnapshots(roundEvidence),
+                evidenceSnapshots: roundEvidence,
+                successTrajectory: input.successTrajectory,
+            });
+            const evaluated = {
+                ...snapshot,
+                attempt,
+                phase: "evaluated",
+                afterEvidence: input.actualEvidence,
+                roundEvidence,
+                evaluation: input.selfEval,
+                result,
+                updatedAt: Date.now(),
+            };
+            if (result.action === "reject" || result.action === "terminate") {
+                const terminalPhase = result.action === "reject" ? "rejected" : "terminated";
+                return finish({
+                    snapshot: { ...evaluated, phase: terminalPhase, updatedAt: Date.now() },
+                    result,
+                    replayed: false,
+                });
+            }
+            const committedSnapshot = {
+                ...evaluated,
+                phase: "committed",
+                updatedAt: Date.now(),
+            };
+            const metadata = {
+                schema_version: ROUND_TRANSACTION_SCHEMA_VERSION,
+                round_id: snapshot.roundId,
+                snapshot: committedSnapshot,
+                result,
+            };
+            this.engine.autoFeedback(input.selfEval, snapshot.loopId, snapshot.round, input.task, metadata);
+            const persisted = this.readCommitted(committedSnapshot);
+            if (!persisted) {
+                throw new Error(`Round transaction commit failed: ${snapshot.roundId}`);
+            }
+            logEvent("round_transaction_commit", {
+                loopId: snapshot.loopId,
+                round: snapshot.round,
+                roundId: snapshot.roundId,
+                action: result.action,
+            });
+            return finish({ snapshot: committedSnapshot, result, replayed: false });
+        }
+        catch (error) {
+            span.end("error", { error: String(error) });
+            throw error;
+        }
+    }
+    /** Recover an already committed decision without evaluating or writing. */
+    recover(snapshot) {
+        const span = startSpan("round.transaction.recover", {
+            loopId: snapshot.loopId,
+            round: snapshot.round,
+            roundId: snapshot.roundId,
+        });
+        try {
+            const outcome = this.readCommitted(snapshot);
+            if (outcome) {
+                policyMetrics.recordRound(snapshot.loopId, outcome.result, true);
+            }
+            span.end("ok", { recovered: outcome !== null });
+            return outcome;
+        }
+        catch (error) {
+            span.end("error", { error: String(error) });
+            throw error;
+        }
+    }
+    readCommitted(expected) {
+        const taskId = `loop:${expected.loopId}:r${expected.round}:feedback`;
+        const entries = this.commitStore.find(expected.loopId, expected.round);
+        for (const entry of entries) {
+            if (entry.task_id !== taskId)
+                continue;
+            const outcome = this.outcomeFromEntry(entry, expected.roundId);
+            if (outcome)
+                return outcome;
+        }
+        return null;
+    }
+    outcomeFromEntry(entry, expectedRoundId) {
+        const lineage = isRecord(entry.loop_lineage) ? entry.loop_lineage : null;
+        const transaction = lineage && isRecord(lineage.round_transaction)
+            ? lineage.round_transaction
+            : null;
+        if (!transaction || transaction.round_id !== expectedRoundId)
+            return null;
+        const snapshot = parseRoundTransactionSnapshot(transaction.snapshot);
+        const result = transaction.result;
+        if (!snapshot || !isProcessResult(result))
+            return null;
+        return { snapshot, result, replayed: true };
+    }
+}
+//# sourceMappingURL=round-transaction.js.map

package/dist/round-transaction.js.map

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

package/dist/self-eval.d.ts

@@ -0,0 +1,26 @@
+/** Self-evaluation extraction and parsing — pure functions.
+ *
+ * These functions parse an Agent's raw output into a structured
+ * SelfEvaluation. They have no dependency on Engine state, file I/O,
+ * or external services. They are shared by both the MCP tool handler
+ * (which receives structured JSON directly) and the legacy invoke
+ * path (which regex-scans free-text Agent output).
+ */
+import { type CriterionRevision, type ExecutionEvidence, type SelfEvaluation } from "./protocol.js";
+/** Parse ExecutionEvidence from a raw JSON object. */
+export declare function parseExecutionEvidence(raw: Record<string, unknown> | undefined | null): ExecutionEvidence | undefined;
+/** Parse CriterionRevision[] from a raw JSON array. */
+export declare function parseCriterionRevisions(raw: unknown): CriterionRevision[];
+/** Parse WorkerResult[] from a raw JSON array. */
+export declare function parseWorkerResults(raw: unknown): import("./protocol.js").WorkerResult[];
+/** Extract a structured SelfEvaluation from agent output text.
+ *  Returns null if no valid self-eval block is found.
+ *  The agent is instructed to output JSON between the delimiters. */
+export declare function extractSelfEvaluation(text: string): SelfEvaluation | null;
+/** Build a SelfEvaluation from a parsed JSON object.
+ *  Lenient parsing: missing optional fields get sensible defaults. */
+export declare function buildSelfEvaluation(raw: Record<string, unknown>): SelfEvaluation;
+/** Fallback heuristic when structured self-eval extraction fails.
+ *  Scans agent output for completion and error signals. */
+export declare function heuristicSelfEvaluation(text: string): SelfEvaluation | null;
+//# sourceMappingURL=self-eval.d.ts.map

package/dist/self-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-eval.d.ts","sourceRoot":"","sources":["../src/self-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAIvB,sDAAsD;AACtD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GAC9C,iBAAiB,GAAG,SAAS,CAwB/B;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,GACX,iBAAiB,EAAE,CAWrB;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,GACX,OAAO,eAAe,EAAE,YAAY,EAAE,CAqBxC;AAID;;qEAEqE;AACrE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAczE;AAED;sEACsE;AACtE,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,cAAc,CA0ChB;AAED;2DAC2D;AAC3D,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAoB3E"}

package/dist/self-eval.js

@@ -0,0 +1,154 @@
+/** Self-evaluation extraction and parsing — pure functions.
+ *
+ * These functions parse an Agent's raw output into a structured
+ * SelfEvaluation. They have no dependency on Engine state, file I/O,
+ * or external services. They are shared by both the MCP tool handler
+ * (which receives structured JSON directly) and the legacy invoke
+ * path (which regex-scans free-text Agent output).
+ */
+import { makeExecutionEvidence, makeSelfEvaluation, SELF_EVAL_REGEX, } from "./protocol.js";
+// ── Raw parsing helpers ───────────────────────────────────────────────────
+/** Parse ExecutionEvidence from a raw JSON object. */
+export function parseExecutionEvidence(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const testResults = raw.test_results;
+    return makeExecutionEvidence({
+        files_changed: Array.isArray(raw.files_changed)
+            ? raw.files_changed.filter((v) => typeof v === "string")
+            : [],
+        test_results: testResults && typeof testResults.passed === "number"
+            ? {
+                passed: testResults.passed,
+                failed: testResults.failed ?? 0,
+                skipped: testResults.skipped ?? 0,
+            }
+            : null,
+        success_criteria_met: Array.isArray(raw.success_criteria_met)
+            ? raw.success_criteria_met.filter((v) => typeof v === "string")
+            : [],
+        success_criteria_remaining: Array.isArray(raw.success_criteria_remaining)
+            ? raw.success_criteria_remaining.filter((v) => typeof v === "string")
+            : [],
+        progress_estimate: typeof raw.progress_estimate === "number"
+            ? Math.max(0, Math.min(1, raw.progress_estimate))
+            : 0.0,
+    });
+}
+/** Parse CriterionRevision[] from a raw JSON array. */
+export function parseCriterionRevisions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((v) => typeof v === "object" && v !== null &&
+        typeof v.old === "string" &&
+        typeof v.new === "string")
+        .map((v) => {
+        const r = v;
+        return { old: r.old, new: r.new };
+    });
+}
+/** Parse WorkerResult[] from a raw JSON array. */
+export function parseWorkerResults(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((v) => typeof v === "object" && v !== null &&
+        typeof v.agentId === "string" &&
+        typeof v.subTask === "string" &&
+        typeof v.resultSummary === "string")
+        .map((v) => {
+        const w = v;
+        return {
+            agentId: w.agentId,
+            subAgentType: typeof w.subAgentType === "string" ? w.subAgentType : "general-purpose",
+            subTask: w.subTask,
+            resultSummary: w.resultSummary,
+            success: typeof w.success === "boolean" ? w.success : false,
+            discoveredConstraints: Array.isArray(w.discoveredConstraints)
+                ? w.discoveredConstraints.filter((c) => typeof c === "string")
+                : [],
+        };
+    });
+}
+// ── Self-evaluation extraction ───────────────────────────────────────────
+/** Extract a structured SelfEvaluation from agent output text.
+ *  Returns null if no valid self-eval block is found.
+ *  The agent is instructed to output JSON between the delimiters. */
+export function extractSelfEvaluation(text) {
+    const match = text.match(SELF_EVAL_REGEX);
+    if (!match)
+        return null;
+    try {
+        const raw = JSON.parse(match[1]);
+        if (typeof raw.success !== "boolean")
+            return null;
+        if (typeof raw.output_summary !== "string")
+            return null;
+        if (!Array.isArray(raw.constraint_violations))
+            return null;
+        if (typeof raw.should_continue !== "boolean")
+            return null;
+        return buildSelfEvaluation(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Build a SelfEvaluation from a parsed JSON object.
+ *  Lenient parsing: missing optional fields get sensible defaults. */
+export function buildSelfEvaluation(raw) {
+    const executionEvidence = parseExecutionEvidence(raw.execution_evidence);
+    const retractedConstraints = Array.isArray(raw.retracted_constraints)
+        ? raw.retracted_constraints.filter((v) => typeof v === "string")
+        : [];
+    const revisedCriteria = parseCriterionRevisions(raw.revised_success_criteria);
+    const wrongAssumptions = Array.isArray(raw.wrong_assumptions)
+        ? raw.wrong_assumptions.filter((v) => typeof v === "string")
+        : [];
+    const workerResults = parseWorkerResults(raw.worker_results);
+    return makeSelfEvaluation({
+        success: typeof raw.success === "boolean" ? raw.success : false,
+        output_summary: typeof raw.output_summary === "string" ? raw.output_summary : "",
+        constraint_violations: Array.isArray(raw.constraint_violations)
+            ? raw.constraint_violations.filter((v) => typeof v === "string")
+            : [],
+        should_continue: typeof raw.should_continue === "boolean" ? raw.should_continue : true,
+        discovered_constraints: Array.isArray(raw.discovered_constraints)
+            ? raw.discovered_constraints.filter((v) => typeof v === "string")
+            : [],
+        objective_refinement: typeof raw.objective_refinement === "string"
+            ? raw.objective_refinement
+            : "",
+        emerged_subtasks: Array.isArray(raw.emerged_subtasks)
+            ? raw.emerged_subtasks.filter((v) => typeof v === "string")
+            : [],
+        execution_evidence: executionEvidence,
+        retracted_constraints: retractedConstraints,
+        revised_success_criteria: revisedCriteria,
+        wrong_assumptions: wrongAssumptions,
+        worker_results: workerResults,
+        compression_checkpoint: typeof raw.compression_checkpoint === "boolean" ? raw.compression_checkpoint : false,
+        checkpoint_label: typeof raw.checkpoint_label === "string" ? raw.checkpoint_label : "",
+        next_action: typeof raw.next_action === "string" ? raw.next_action : undefined,
+    });
+}
+/** Fallback heuristic when structured self-eval extraction fails.
+ *  Scans agent output for completion and error signals. */
+export function heuristicSelfEvaluation(text) {
+    const lower = text.toLowerCase();
+    const hasError = /error|failed|exception|cannot|unable|失败|错误|异常/.test(lower);
+    const hasCompletion = /done|complete|finished|完成|成功/.test(lower);
+    const hasRemaining = /remaining|continue|still need|next|todo|剩余|继续|下一步/.test(lower);
+    const paragraphs = text.split(/\n\n+/).filter((p) => p.trim().length > 30);
+    const summary = paragraphs.length > 0
+        ? paragraphs[paragraphs.length - 1].trim().slice(0, 300)
+        : text.trim().slice(0, 300);
+    return makeSelfEvaluation({
+        success: !hasError && (hasCompletion || !hasRemaining),
+        output_summary: summary || "[heuristic fallback — could not parse structured self-eval]",
+        constraint_violations: [],
+        should_continue: hasRemaining && !hasError,
+    });
+}
+//# sourceMappingURL=self-eval.js.map

package/dist/self-eval.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,39 @@
+/** Persistence adapters for session state and committed round lookup. */
+import type { VaultBackend, VaultEntry } from "./backends/interface.js";
+import type { LoopStore } from "./loop-store.js";
+export interface SessionStateStore {
+    load(loopId: string): VaultEntry | undefined;
+    list(): VaultEntry[];
+    save(entry: VaultEntry, options?: SessionSaveOptions): void;
+    acquireLease?(loopId: string, ownerId: string, leaseMs: number, now?: number): VaultEntry | undefined;
+    renewLease?(loopId: string, ownerId: string, leaseMs: number, now?: number): boolean;
+    releaseLease?(loopId: string, ownerId: string): boolean;
+}
+export interface SessionSaveOptions {
+    /** Reject a write if another process owns the existing session entry. */
+    expectedLeaseOwner?: string;
+}
+export declare class SessionLeaseConflictError extends Error {
+    readonly loopId: string;
+    constructor(loopId: string);
+}
+export interface RoundCommitStore {
+    find(loopId: string, round: number): VaultEntry[];
+}
+export declare class VaultSessionStateStore implements SessionStateStore {
+    private readonly store;
+    constructor(store: LoopStore);
+    load(loopId: string): VaultEntry | undefined;
+    list(): VaultEntry[];
+    save(entry: VaultEntry, options?: SessionSaveOptions): void;
+    acquireLease(loopId: string, ownerId: string, leaseMs: number, now?: number): VaultEntry | undefined;
+    renewLease(loopId: string, ownerId: string, leaseMs: number, now?: number): boolean;
+    releaseLease(loopId: string, ownerId: string): boolean;
+    private lineage;
+}
+export declare class VaultRoundCommitStore implements RoundCommitStore {
+    private readonly backend;
+    constructor(backend: VaultBackend);
+    find(loopId: string, round: number): VaultEntry[];
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAuB,MAAM,iBAAiB,CAAC;AAgBtE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7C,IAAI,IAAI,UAAU,EAAE,CAAC;IACrB,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC5D,YAAY,CAAC,CACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,GAAG,SAAS,CAAC;IAC1B,UAAU,CAAC,CACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC;IACX,YAAY,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACzD;AAED,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;CACnD;AAED,qBAAa,sBAAuB,YAAW,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,SAAS;IAE7C,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAK5C,IAAI,IAAI,UAAU,EAAE;IASpB,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,kBAAuB,GAAG,IAAI;IA2B/D,YAAY,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,SAAa,GACf,UAAU,GAAG,SAAS;IA6CzB,UAAU,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,SAAa,GACf,OAAO;IA4BV,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IA6BtD,OAAO,CAAC,OAAO;CAOhB;AAED,qBAAa,qBAAsB,YAAW,gBAAgB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAElD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE;CAMlD"}