@telora/daemon 0.19.43 → 0.19.74

package/dist/focus-stage-lifecycle/planning-release.js

@@ -0,0 +1,312 @@
+/**
+ * Planning->execution delivery releases (extracted from focus-stage-lifecycle).
+ *
+ * Owns the two planning->queued release paths:
+ *   - `releaseRatifiedReadOnlyFocus`  -- the SOLE human-ratified planning->execution
+ *     crossing for a read-only audit focus.
+ *   - `releaseWritableFocusPlanningDeliveries` -- the writable-focus analogue that
+ *     closes the silent born-planning wedge for a normal execute focus.
+ *
+ * Plus the pure predicates (`isFocusRatifiedForExecute`,
+ * `isWritableFocusPastKickoff`) that gate them.
+ *
+ * @module focus-stage-lifecycle/planning-release
+ */
+import { getFocusDeliveries as defaultGetFocusDeliveries, updateFocusReadOnly as defaultUpdateFocusReadOnly, } from '../queries/focuses.js';
+import { updateDeliveryStatus as defaultUpdateDeliveryStatus } from '../queries/deliveries.js';
+import { DELIVERY_STATUS } from '@telora/daemon-core';
+import { emitLoopTrigger } from '../loops/index.js';
+import { deriveFocusPhase } from '../focus-phase.js';
+import { hasActiveTeam as defaultHasActiveTeam } from '../focus-team-state.js';
+import { isAuditPhaseFocus } from '../audit-shape.js';
+// ── Ratify-to-execute release (Safe audit-to-remediation D3) ──────
+/**
+ * Pure predicate: a read-only focus is ready to cross planning->execution
+ * exactly when a human has ratified its remediation plan.
+ *
+ *   read_only === true  => the focus is in the audit/read-only phase, its
+ *                          remediation deliveries held in 'planning'.
+ *   ratified_at != null => a human stamped the distinct ratification signal.
+ *
+ * Both must hold. read_only=false (already crossed / a normal execute focus)
+ * fails the predicate, which is what makes the release idempotent: after the
+ * crossing flips read_only=false the predicate no longer holds, so re-runs are
+ * no-ops. A null ratified_at means the gate has NOT been crossed -- the human
+ * signal is absent -- so the focus stays held.
+ *
+ * Exported so tests can drive it with synthetic focus shapes.
+ */
+export function isFocusRatifiedForExecute(focus) {
+    return focus.readOnly === true && focus.ratifiedAt != null;
+}
+const defaultRatifyReleaseDeps = {
+    getFocusDeliveries: defaultGetFocusDeliveries,
+    updateFocusReadOnly: defaultUpdateFocusReadOnly,
+    updateDeliveryStatus: defaultUpdateDeliveryStatus,
+    emitLoopTrigger,
+};
+/**
+ * The SOLE planning->execution crossing for a read-only audit focus.
+ *
+ * When `isFocusRatifiedForExecute(focus)` holds (read_only=true AND a human
+ * stamped ratified_at), atomically-in-effect:
+ *   (a) flip read_only=false, and
+ *   (b) release every held delivery (execution_status 'planning') to 'queued'.
+ *
+ * This is the ONLY path that does either, which is what makes the gate
+ * non-procedural: the gate cannot be crossed by an agent or a stage transition;
+ * it requires the distinct human ratification signal that this function reads.
+ *
+ * Idempotent by construction:
+ *   - flipping read_only=false first means the predicate fails on re-entry, so a
+ *     second tick is a no-op;
+ *   - the delivery move is guarded to ONLY touch 'planning' rows, so deliveries
+ *     already queued (or further along) are left untouched.
+ *
+ * Returns the number of deliveries released (0 when the predicate does not hold
+ * or there were no held deliveries).
+ *
+ * Runs regardless of stage: a read-only audit focus may sit at planning/queued/
+ * in_progress, so this is NOT gated on focus.stage.
+ */
+export async function releaseRatifiedReadOnlyFocus(focus, deps = defaultRatifyReleaseDeps) {
+    if (!isFocusRatifiedForExecute(focus))
+        return 0;
+    // Crash-safety ordering: release held deliveries FIRST, and flip
+    // read_only=false ONLY after every held 'planning' delivery has been queued.
+    // The flip is what makes the predicate fail on re-entry, so deferring it
+    // until the release is complete means a crash (or a partial failure)
+    // mid-release leaves the predicate TRUE (read_only still true) and the next
+    // tick retries the whole release. Flipping first would orphan any
+    // not-yet-released held delivery: the predicate would already be false and
+    // those deliveries would never be queued.
+    // (a) Release held deliveries: planning -> queued. Guarded so only 'planning'
+    // rows move; anything already queued/further-along is left untouched
+    // (idempotency + safety).
+    let deliveries;
+    try {
+        deliveries = await deps.getFocusDeliveries(focus.focusId);
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Ratify-release: failed to fetch deliveries to ` +
+            `release for "${focus.focusName}" (leaving read_only=true to retry next ` +
+            `tick): ${err.message}`);
+        return 0;
+    }
+    let released = 0;
+    let allReleased = true;
+    for (const d of deliveries) {
+        if (d.executionStatus !== DELIVERY_STATUS.PLANNING)
+            continue;
+        try {
+            await deps.updateDeliveryStatus(d.id, DELIVERY_STATUS.QUEUED, undefined, undefined, undefined, { organizationId: focus.organizationId, fromStatus: DELIVERY_STATUS.PLANNING });
+            released += 1;
+        }
+        catch (err) {
+            allReleased = false;
+            console.warn(`[focus-stage-lifecycle] Ratify-release: failed to queue held delivery ` +
+                `${d.id.slice(0, 8)} on "${focus.focusName}": ${err.message}`);
+        }
+    }
+    // (b) Flip read_only=false ONLY when every held delivery was queued. If any
+    // release failed, leave read_only=true so the predicate stays satisfied and
+    // the next tick retries the (planning-only, idempotent) release -- never
+    // crossing the gate with held deliveries still stuck in planning.
+    if (!allReleased) {
+        console.warn(`[focus-stage-lifecycle] Ratify-release: not all held deliveries queued ` +
+            `for "${focus.focusName}" (released ${released}); leaving read_only=true ` +
+            `to retry next tick.`);
+        return released;
+    }
+    try {
+        await deps.updateFocusReadOnly(focus.focusId, false);
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Ratify-release: held deliveries queued for ` +
+            `"${focus.focusName}" but failed to flip read_only=false (will retry ` +
+            `next tick): ${err.message}`);
+        return released;
+    }
+    console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" ratified -> execute: ` +
+        `read_only=false, released ${released} held planning ` +
+        `deliver${released === 1 ? 'y' : 'ies'} to queued.`);
+    deps.emitLoopTrigger({
+        type: 'focus_status_changed',
+        focusId: focus.focusId,
+        detail: 'ratify:read_only->execute',
+    });
+    return released;
+}
+// ── Writable-focus planning->queued release (planning-wedge prevention D1) ──
+/**
+ * Pure predicate: a writable focus is PAST its planning/kickoff window -- i.e. a
+ * lingering 'planning' delivery on it is a WEDGE to release, not work a scoping
+ * team is still shaping.
+ *
+ * Stage-column-INDEPENDENT by design. The previous version gated on
+ * `isPostPlanning(focus.stage)`, but `product_focuses.stage` is a documented-stale
+ * column: NO live path advances it to 'queued'/'in_progress' (the daemon writes
+ * only review/close_loop/done; everything else keeps the 'planning' default).
+ * supabase/.../focus/lifecycle.ts says so explicitly ("nothing advances `stage`
+ * to 'verify'"), which is why the newer code (checkAutoReview, focus_transition_stage)
+ * gates on the DERIVED phase instead. The old stage gate therefore NEVER fired for
+ * the founding wedge -- a post-backfill writable focus whose stage stays 'planning'
+ * forever (review finding, delivery 18055ddd). Worse, it was self-defeating: a
+ * delivery is born 'planning' PRECISELY because focus.stage was not post-planning
+ * (MCP resolveDefaultExecutionStatus reads the same column), and nothing changes
+ * the column before this tick -- so the release could never see a post-planning
+ * stage for exactly the focuses that have born-planning deliveries.
+ *
+ * The replacement uses two stage-free signals:
+ *   1. read_only === false -- a NORMAL execute focus, not a read-only audit focus
+ *      (whose held planning deliveries are released only by the human-ratified
+ *      `releaseRatifiedReadOnlyFocus`).
+ *   2. "past kickoff" via the delivery aggregate + active-team:
+ *        - deriveFocusPhase(deliveries) !== 'kickoff'  => real work already exists
+ *          (some delivery is queued/coding/verify/done), so a lingering 'planning'
+ *          row is a wedge behind/ahead of it -> past kickoff.
+ *        - phase === 'kickoff' (all deliveries planning/draft, or none): genuinely
+ *          ambiguous between a live scoping window and a full wedge. An ACTIVE TEAM
+ *          is the discriminator -- a scoping team running for the focus is (or just
+ *          was) creating/releasing deliveries, so DON'T pre-empt it; no team means
+ *          nothing can make progress (the rank-0 planning delivery blocks the ready
+ *          selector so no team will ever spawn) -> wedge -> past kickoff.
+ *
+ * Second discovery-only signal (injection #7, TEL-3): signal 1 is widened from a
+ * bare `read_only === false` to "NOT audit-phase". An audit-origin, not-yet-
+ * ratified focus whose `read_only` is silently absent (coerced false) is STILL an
+ * audit focus -- its born-planning remediation deliveries are owned by the ratify
+ * path and must NOT be swept to queued here, or the remediation executes ahead of
+ * the human ratify gate (2f253da6). `isAuditPhaseFocus` captures read_only===true
+ * OR (audit_origin AND !ratified); a RATIFIED audit focus (read_only=false,
+ * ratified_at set) is NOT audit-phase and IS released normally, and a NORMAL focus
+ * (audit_origin=false) is unaffected. Keyed on audit_origin + ratified_at
+ * (provenance + phase) -- it never writes read_only, so it is not a second source
+ * of truth for the flag.
+ *
+ * Exported so tests can drive it with synthetic shapes.
+ */
+export function isWritableFocusPastKickoff(input) {
+    // Audit-phase focuses (explicit read_only=true OR the second structural signal:
+    // audit_origin && not-yet-ratified) are owned by the ratify-release path.
+    if (isAuditPhaseFocus({
+        readOnly: input.readOnly === true,
+        auditOrigin: input.auditOrigin === true,
+        ratified: input.ratifiedAt != null,
+    })) {
+        return false;
+    }
+    if (input.readOnly !== false)
+        return false;
+    const phase = deriveFocusPhase({
+        deliveries: input.deliveries.map((d) => ({ executionStatus: d.executionStatus })),
+        reviewRequestedAt: input.reviewRequestedAt ?? null,
+    });
+    // Any non-kickoff phase => real work exists => a held planning row is a wedge.
+    if (phase !== 'kickoff')
+        return true;
+    // Pure all-planning/draft (or empty) 'kickoff': a wedge only when no team is
+    // (or can be) working it. An active scoping team is shaping deliveries -- leave it.
+    return !input.hasActiveTeam;
+}
+const defaultWritableReleaseDeps = {
+    getFocusDeliveries: defaultGetFocusDeliveries,
+    updateDeliveryStatus: defaultUpdateDeliveryStatus,
+    emitLoopTrigger,
+    hasActiveTeam: defaultHasActiveTeam,
+};
+/**
+ * The writable-focus analogue of `releaseRatifiedReadOnlyFocus`: the missing
+ * planning->queued release for a NORMAL (read_only=false) executing focus.
+ *
+ * Closes the silent wedge: a writable focus whose deliveries were born
+ * 'planning' (created during the planning stage, or via the MCP focus_list
+ * lookup falling back to 'planning') has NO transition that releases them once
+ * the focus is past planning -- the only planning->queued release in the
+ * codebase (`releaseRatifiedReadOnlyFocus`) is gated to ratified read-only audit
+ * focuses, and listener-auto-advance only moves queued/coding -> verify. So
+ * `daemon_get_ready_focuses` hits the rank-0 'planning' delivery, treats it as a
+ * hard block, and the focus never spawns a team.
+ *
+ * Fetch the focus's deliveries, and when `isWritableFocusPastKickoff` holds (the
+ * stage-column-independent gate), sweep every held delivery (execution_status
+ * 'planning') to 'queued'. Guarded so ONLY 'planning' rows move --
+ * draft/paused/queued/further-along are left untouched, which also makes the
+ * release idempotent: once swept, there are no 'planning' rows left so a re-run is
+ * a no-op. Unlike the ratify path there is no read_only flip to defer, so each
+ * delivery move stands on its own; a per-delivery failure is logged and retried on
+ * the next tick.
+ *
+ * FRT effect #6 (a completed/merged delivery stuck in 'planning' must advance out
+ * of 'planning' and never block at rank 0): planning's ONLY valid forward
+ * transition is 'queued' (DELIVERY_STATUS machine: planning -> queued|cancelled;
+ * planning -> done is illegal). So 'queued' is the correct -- and only -- forward
+ * move here even for a complete-but-mislabeled row: it advances out of 'planning'
+ * and re-enters the normal lifecycle, which re-settles already-done work quickly
+ * (its issues are already Done -> coding -> verify -> done). Re-running merged work
+ * is bounded by that; skipping the row instead would leave it 'planning' and
+ * re-wedge the focus, which is worse.
+ *
+ * Returns the number of deliveries released (0 when the gate does not hold or
+ * there were no held deliveries).
+ */
+export async function releaseWritableFocusPlanningDeliveries(focus, deps = defaultWritableReleaseDeps) {
+    // Audit-phase focuses -- explicit read_only=true OR the second structural signal
+    // (audit_origin && not-yet-ratified) -- are owned by the ratify-release path.
+    // Cheap exit before the fetch (isWritableFocusPastKickoff re-checks). Without
+    // this a flag-absent audit focus (read_only silently false) would sweep its
+    // born-planning remediation delivery to queued ahead of ratification (2f253da6).
+    if (isAuditPhaseFocus({
+        readOnly: focus.readOnly === true,
+        auditOrigin: focus.auditOrigin === true,
+        ratified: focus.ratifiedAt != null,
+    })) {
+        return 0;
+    }
+    if (focus.readOnly !== false)
+        return 0;
+    let deliveries;
+    try {
+        deliveries = await deps.getFocusDeliveries(focus.focusId);
+    }
+    catch (err) {
+        console.warn(`[focus-stage-lifecycle] Writable-release: failed to fetch deliveries to ` +
+            `release for "${focus.focusName}" (retry next tick): ${err.message}`);
+        return 0;
+    }
+    // Stage-column-INDEPENDENT gate: derived phase + active-team, never focus.stage.
+    if (!isWritableFocusPastKickoff({
+        readOnly: focus.readOnly,
+        auditOrigin: focus.auditOrigin,
+        ratifiedAt: focus.ratifiedAt,
+        deliveries,
+        reviewRequestedAt: focus.reviewRequestedAt,
+        hasActiveTeam: deps.hasActiveTeam(focus.focusId),
+    })) {
+        return 0;
+    }
+    let released = 0;
+    for (const d of deliveries) {
+        if (d.executionStatus !== DELIVERY_STATUS.PLANNING)
+            continue;
+        try {
+            await deps.updateDeliveryStatus(d.id, DELIVERY_STATUS.QUEUED, undefined, undefined, undefined, { organizationId: focus.organizationId, fromStatus: DELIVERY_STATUS.PLANNING });
+            released += 1;
+        }
+        catch (err) {
+            console.warn(`[focus-stage-lifecycle] Writable-release: failed to queue held delivery ` +
+                `${d.id.slice(0, 8)} on "${focus.focusName}": ${err.message}`);
+        }
+    }
+    if (released > 0) {
+        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" (writable, past kickoff): ` +
+            `released ${released} born-planning deliver${released === 1 ? 'y' : 'ies'} to queued.`);
+        deps.emitLoopTrigger({
+            type: 'focus_status_changed',
+            focusId: focus.focusId,
+            detail: 'writable:planning->queued',
+        });
+    }
+    return released;
+}
+//# sourceMappingURL=planning-release.js.map

package/dist/focus-stage-lifecycle/planning-release.js.map

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

package/dist/focus-stage-lifecycle/review-convergence.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Focus review-convergence transitions (extracted from focus-stage-lifecycle).
+ *
+ * Owns the two review-axis daemon-side transitions:
+ *   verify  -> review     (Issue 4: auto-enter review on verify-stage entry)
+ *   review  -> close_loop (Issue 2 + 3: state-based convergence / nonconvergent
+ *                          escalation)
+ *
+ * Plus the pure helpers (`hasReviewConverged`, `getReviewIterationCap`,
+ * `hasInFlightRemediations`) these transitions rely on.
+ *
+ * @module focus-stage-lifecycle/review-convergence
+ */
+import type { PipelineConfig } from '../types.js';
+import { getLatestCompletedFocusReview as defaultGetLatestCompletedFocusReview, getInFlightRemediationCount as defaultGetInFlightRemediationCount, getFocusReviewIterationCount as defaultGetFocusReviewIterationCount, updateFocusStage as defaultUpdateFocusStage } from '../queries/focuses.js';
+import { createEscalation as defaultCreateEscalation } from '../queries/issues.js';
+import { emitLoopTrigger } from '../loops/index.js';
+/**
+ * Default cap on review iterations before the daemon files a
+ * `review_nonconvergent` escalation and pauses the focus.
+ *
+ * Configurable per focus via `pipeline_config.review.maxIterations`.
+ */
+export declare const DEFAULT_REVIEW_MAX_ITERATIONS = 3;
+/**
+ * Decide whether a focus has converged out of review. Convergence is
+ * deterministic and state-based:
+ *
+ *   - If there are no in-flight remediation deliveries created during/after
+ *     the latest review pass, the focus has converged.
+ *
+ * Pure function: takes the in-flight count and returns the decision.
+ * Exported so tests can drive it with synthetic counts.
+ */
+export declare function hasReviewConverged(inFlightRemediationCount: number): boolean;
+/**
+ * Compute the configured review iteration cap for a focus. Pulls
+ * `pipeline_config.review.maxIterations` and falls back to
+ * `DEFAULT_REVIEW_MAX_ITERATIONS` when unset or non-positive.
+ *
+ * Exported for unit testing.
+ */
+export declare function getReviewIterationCap(pipelineConfig: PipelineConfig | null | undefined): number;
+/**
+ * Returns true when the focus has any in-flight remediation deliveries
+ * created during/after the latest review pass.
+ *
+ * "Latest review pass" is the `started_at` of the most recent focus_reviews
+ * row; when no review has run yet, this returns false (no remediation
+ * deliveries can exist before a review pass).
+ *
+ * In-flight means execution_status is NOT one of done/cancelled/verify.
+ *
+ * Exported for unit testing the convergence query independently of the
+ * surrounding transition logic.
+ */
+export declare function hasInFlightRemediations(focusId: string, latestReviewPassTimestamp: string | null, deps?: {
+    getInFlightRemediationCount: typeof defaultGetInFlightRemediationCount;
+}): Promise<boolean>;
+/**
+ * Dependencies for `advanceVerifyToReviewIfEnabled`. Defaults reach for the
+ * real query module; tests can pass stub implementations.
+ */
+export interface VerifyToReviewDeps {
+    updateFocusStage: typeof defaultUpdateFocusStage;
+    emitLoopTrigger: typeof emitLoopTrigger;
+}
+/**
+ * When a focus's stage is `verify` and auto-review is enabled, advance it to
+ * `review`. Auto-review is default-on (`isReviewEnabled`): only an explicit
+ * `pipeline_config.review.enabled === false` keeps the focus at `verify` until
+ * a human signals review. A focus with no stored review key auto-advances.
+ *
+ * Returns true when an advance was performed.
+ */
+export declare function advanceVerifyToReviewIfEnabled(focus: {
+    focusId: string;
+    focusName: string;
+    stage: string;
+    pipelineConfig: PipelineConfig | null;
+}, deps?: VerifyToReviewDeps): Promise<boolean>;
+/**
+ * Dependencies for `advanceReviewToCloseLoopIfConverged`. Defaults reach for
+ * the real query modules; tests can pass stub implementations.
+ */
+export interface ReviewConvergeDeps {
+    getLatestCompletedFocusReview: typeof defaultGetLatestCompletedFocusReview;
+    getInFlightRemediationCount: typeof defaultGetInFlightRemediationCount;
+    getFocusReviewIterationCount: typeof defaultGetFocusReviewIterationCount;
+    updateFocusStage: typeof defaultUpdateFocusStage;
+    createEscalation: typeof defaultCreateEscalation;
+    emitLoopTrigger: typeof emitLoopTrigger;
+}
+/**
+ * Outcome of an attempt to advance a focus past the review stage.
+ */
+export type ReviewTransitionOutcome = {
+    kind: 'no_action';
+    reason: string;
+} | {
+    kind: 'converged';
+    from: 'review';
+    to: 'close_loop';
+} | {
+    kind: 'nonconvergent';
+    iterations: number;
+    cap: number;
+};
+/**
+ * Evaluate the review -> close_loop transition for a focus and apply the
+ * appropriate action. Returns a structured outcome so callers can log /
+ * test the decision path.
+ *
+ * Logic:
+ *   1. If stage is not `review`, do nothing.
+ *   2. If the review iteration count is >= the cap, file a
+ *      `review_nonconvergent` escalation (idempotent best-effort) and
+ *      LEAVE the focus stage at `review`. The focus is paused until a
+ *      human intervenes.
+ *   3. Otherwise, check in-flight remediations against the latest review
+ *      pass. If zero, advance stage `review -> close_loop`.
+ *   4. Otherwise, do nothing -- remediations are still in flight.
+ *
+ * Exported with injectable deps for unit testing.
+ */
+export declare function advanceReviewToCloseLoopIfConverged(focus: {
+    focusId: string;
+    focusName: string;
+    organizationId: string;
+    stage: string;
+    pipelineConfig: PipelineConfig | null;
+}, deps?: ReviewConvergeDeps): Promise<ReviewTransitionOutcome>;
+//# sourceMappingURL=review-convergence.d.ts.map

package/dist/focus-stage-lifecycle/review-convergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-convergence.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/review-convergence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,6BAA6B,IAAI,oCAAoC,EACrE,2BAA2B,IAAI,kCAAkC,EACjE,4BAA4B,IAAI,mCAAmC,EACnE,gBAAgB,IAAI,uBAAuB,EAC5C,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,IAAI,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAOnF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKpD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAI/C;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,wBAAwB,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,CAMR;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,yBAAyB,EAAE,MAAM,GAAG,IAAI,EACxC,IAAI,GAAE;IACJ,2BAA2B,EAAE,OAAO,kCAAkC,CAAC;CACF,GACtE,OAAO,CAAC,OAAO,CAAC,CASlB;AAID;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,eAAe,EAAE,OAAO,eAAe,CAAC;CACzC;AAOD;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;CACvC,EACD,IAAI,GAAE,kBAA8C,GACnD,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAID;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B,EAAE,OAAO,oCAAoC,CAAC;IAC3E,2BAA2B,EAAE,OAAO,kCAAkC,CAAC;IACvE,4BAA4B,EAAE,OAAO,mCAAmC,CAAC;IACzE,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,eAAe,EAAE,OAAO,eAAe,CAAC;CACzC;AAWD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mCAAmC,CACvD,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;CACvC,EACD,IAAI,GAAE,kBAA8C,GACnD,OAAO,CAAC,uBAAuB,CAAC,CAqHlC"}