@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/core/sdk-sessions-merge.js

@@ -0,0 +1,220 @@
+/*
+ * F08 (D04) — multi-instance 3-way merge for SdkSessionsStore.persist().
+ *
+ * sdk-sessions.json is shared by every webui server on the machine
+ * (registryDir is keyed to os.homedir(), config.ts). persist() re-reads the
+ * file UNDER the proper-lockfile critical section and reconciles it via these
+ * pure helpers, so a concurrent instance's rows and externally-written daemon
+ * claim fields survive: for every shared row only the FIELDS this instance
+ * actually changed (baseline → memory) are re-applied on top of the current
+ * on-disk row; every other field — including claimToken / claimedBy written
+ * out-of-band — is taken from disk. Rows added / deleted by either side
+ * reconcile by presence.
+ *
+ * `ExternalTask` has no `updatedAt`, so a last-writer timestamp tiebreak is
+ * impossible. The baseline is a deep-copied snapshot taken at load() and
+ * refreshed after each successful persist; comparing baseline → memory is
+ * precisely what tells this instance which fields it owns.
+ */
+import { randomUUID } from "node:crypto";
+import { rename as fsRename, unlink as fsUnlink } from "node:fs/promises";
+/** fs error `code`s that are transient on Windows — retried (CLAUDE.md rule 6). */
+const RETRYABLE_FS_CODES = new Set(["EBUSY", "EPERM", "EACCES"]);
+/** Deep structural equality for JSON-shaped ExternalTask values. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ao = a;
+        const bo = b;
+        const ka = Object.keys(ao);
+        if (ka.length !== Object.keys(bo).length)
+            return false;
+        return ka.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]));
+    }
+    return false;
+}
+/** Deep-copy a sessions map so the baseline snapshot can't alias live rows. */
+export function cloneSessions(sessions) {
+    const out = new Map();
+    for (const [id, task] of sessions)
+        out.set(id, structuredClone(task));
+    return out;
+}
+/**
+ * Merge this instance's local changes (baseline → memory) onto the current
+ * on-disk state (disk). `deleted` is the set of ids this instance removed since
+ * baseline — they are dropped UNCONDITIONALLY (a delete wins over a concurrent
+ * instance's poll rewrite; taskIds are random UUIDs, never reused). Returns a
+ * fresh map; the inputs are never mutated.
+ */
+export function mergeSessions(baseline, memory, disk, deleted) {
+    const out = new Map();
+    const ids = new Set([...baseline.keys(), ...memory.keys(), ...disk.keys()]);
+    for (const id of ids) {
+        if (deleted.has(id))
+            continue; // this instance deleted it → delete always wins
+        const base = baseline.get(id);
+        const mem = memory.get(id);
+        const dsk = disk.get(id);
+        if (mem && dsk) {
+            out.set(id, mergeRow(base, mem, dsk));
+        }
+        else if (mem) {
+            // Absent on disk. If this instance never touched it and a baseline
+            // exists, another instance deleted it → honor the delete. Otherwise
+            // (created here, or locally modified) keep this instance's row.
+            if (base && deepEqual(base, mem))
+                continue;
+            out.set(id, structuredClone(mem));
+        }
+        else if (dsk) {
+            // Not in memory and NOT locally deleted (that set was handled above).
+            // A baseline means it vanished from memory some other way — drop only
+            // when disk is unchanged; else a foreign row / concurrent edit: keep it.
+            if (base && deepEqual(base, dsk))
+                continue;
+            out.set(id, structuredClone(dsk));
+        }
+    }
+    return out;
+}
+/**
+ * Classify the on-disk bytes for a merge re-read (pure; no side effects). Empty
+ * / whitespace is a legitimately-empty store. Corrupt = unparseable JSON, a
+ * non-object root, a malformed `sessions`, or a non-integer / < 1 schemaVersion.
+ * Future = valid JSON whose integer schemaVersion is GREATER than this build's.
+ */
+export function classifyDiskRaw(raw, current) {
+    if (!raw.trim())
+        return { kind: "ok", schemaVersion: current, sessions: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "corrupt" };
+    }
+    if (!parsed || typeof parsed !== "object")
+        return { kind: "corrupt" };
+    const v = parsed.schemaVersion;
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1)
+        return { kind: "corrupt" };
+    if (v > current)
+        return { kind: "future" };
+    const sessions = parsed.sessions;
+    if (!sessions || typeof sessions !== "object")
+        return { kind: "corrupt" };
+    return { kind: "ok", schemaVersion: v, sessions: sessions };
+}
+/** Retry a transient (EBUSY/EPERM/EACCES) fs op up to 6× with 50→1600 ms backoff. */
+async function withFsRetry(op) {
+    let delay = 50;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            const code = err.code;
+            if (attempt >= 5 || !code || !RETRYABLE_FS_CODES.has(code))
+                throw err;
+            await new Promise((r) => setTimeout(r, delay));
+            delay = Math.min(delay * 2, 1600);
+        }
+    }
+}
+/**
+ * Re-read + classify + validate the on-disk file for a persist merge. A missing
+ * file / ENOENT is an empty store; a TRANSIENT read error (EBUSY/EPERM/EACCES)
+ * is retried, then re-thrown (the caller must reject, NOT full-write — that
+ * would clobber a concurrent instance's rows). Returns "corrupt"/"future" for
+ * the caller to recover / abort. Reuses the store's row validator (injected to
+ * avoid a store↔merge import cycle).
+ */
+export async function reReadDisk(deps, path, current, validate) {
+    const raw = deps.existsSync(path)
+        ? await withFsRetry(() => deps.readFile(path, "utf-8").catch((err) => {
+            if (err?.code === "ENOENT")
+                return ""; // vanished mid-flight → empty store
+            throw err;
+        }))
+        : "";
+    const cls = classifyDiskRaw(raw, current);
+    if (cls.kind !== "ok")
+        return cls;
+    const disk = new Map();
+    for (const [id, value] of Object.entries(cls.sessions)) {
+        const task = validate(id, value, cls.schemaVersion);
+        if (task)
+            disk.set(id, task);
+    }
+    return { kind: "ok", disk };
+}
+/**
+ * Atomic-rename with a bounded EBUSY/EPERM/EACCES backoff (6 attempts,
+ * 50→1600 ms) — mirrors the torn-read budget (CLAUDE.md rule 6) so a transient
+ * Windows file lock on the rename target doesn't fail the persist.
+ */
+async function renameWithRetry(rename, from, to) {
+    await withFsRetry(() => rename(from, to));
+}
+/**
+ * Atomic write: stage to a unique `<path>.tmp-*` (a mid-write crash lands there,
+ * never truncating the live file) then rename it into place — using the
+ * injected `rename`, else the fs default when a lock is held (real fs), with the
+ * EBUSY/EPERM/EACCES retry + best-effort temp cleanup. Lock-less test doubles
+ * (no injected rename) fall back to an in-place write of the SAME payload.
+ */
+export async function atomicWriteFile(deps, path, data, hasLock) {
+    const tmp = `${path}.tmp-${randomUUID()}`;
+    await deps.writeFile(tmp, data);
+    const doRename = deps.rename ?? (hasLock ? fsRename : undefined);
+    if (!doRename) {
+        await deps.writeFile(path, data);
+        return;
+    }
+    try {
+        await renameWithRetry(doRename, tmp, path);
+    }
+    catch (err) {
+        try {
+            await fsUnlink(tmp);
+        }
+        catch { /* best-effort temp cleanup */ }
+        throw err;
+    }
+}
+/**
+ * Field-level 3-way merge of a row present in both memory and disk. Start from
+ * the on-disk row (foreign updates + external claim fields), then re-apply
+ * every field this instance actually changed (baseline → memory), including
+ * fields it removed.
+ */
+function mergeRow(base, mem, dsk) {
+    const out = structuredClone(dsk);
+    const keys = new Set([
+        ...Object.keys(mem),
+        ...(base ? Object.keys(base) : []),
+    ]);
+    for (const k of keys) {
+        const memVal = mem[k];
+        const baseVal = base ? base[k] : undefined;
+        if (deepEqual(memVal, baseVal))
+            continue; // this instance did not change it
+        if (memVal === undefined)
+            delete out[k];
+        else
+            out[k] = structuredClone(memVal);
+    }
+    return out;
+}
+//# sourceMappingURL=sdk-sessions-merge.js.map

package/server/dist/core/sdk-sessions-merge.js.map

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

package/server/dist/core/sdk-sessions-store.d.ts

@@ -0,0 +1,261 @@
+import type { BoardColumn } from "./board-column.js";
+import type { MissionContextAssociation } from "./mission-context/types.js";
+export { UNASSIGNED_PROJECT_ID } from "./sdk-sessions-validate.js";
+export type ExternalTaskState = "draft" | "awaiting_external_start" | "active" | "idle" | "jsonl_missing" | "launch_failed" | "done";
+/**
+ * The five "In Progress" states — a task that has been launched but is
+ * not yet `done`. These are exactly the states from which a task can be
+ * moved back to the Backlog (`POST /api/external/tasks/:id/backlog`,
+ * iterate-2026-05-17-move-to-backlog / FR-01.32). `draft` (already in
+ * Backlog) and `done` (terminal) are deliberately excluded.
+ *
+ * Verbatim mirror: `client/src/lib/taskLifecycle.ts` IN_PROGRESS_STATES.
+ * The two halves are independent npm workspaces (DO-NOT guard #7 — no
+ * cross-package import); keep this tuple and the client one in sync.
+ */
+export declare const BACKLOG_SOURCE_STATES: readonly ["awaiting_external_start", "active", "idle", "jsonl_missing", "launch_failed"];
+/** True when `state` is one of the five In-Progress {@link BACKLOG_SOURCE_STATES}. */
+export declare function isBacklogSourceState(state: ExternalTaskState): boolean;
+export interface ExternalTaskInboxState {
+    pendingToolUseIds: string[];
+    dismissedToolUseIds: string[];
+    /** Byte offset in the JSONL up to which inbox-derive has processed. */
+    lastProcessedByteOffset: number;
+}
+/**
+ * iterate-2026-05-14 lead-foundation-task-schema — leadwright Phase 1.
+ * Canonical source: leadwright/lib/lead-task-extension.ts (separate repo).
+ * Inlined here per the spec's "Open questions" — the duplicated surface
+ * is ~30 LOC and avoids cross-repo npm-link coupling. Field shapes are
+ * locked; do not extend without revisiting that decision.
+ *
+ * Sub-object on `ExternalTask.leadHandoff` capturing the daemon-recorded
+ * outcome of a lead-claimed task. Status is the discriminator; a row
+ * whose status is outside the enum has the entire field dropped on load.
+ */
+export interface LeadHandoff {
+    leadId: string;
+    status: "completed" | "escalated" | "failed";
+    beatsUsed: number;
+    subIterateIds?: string[];
+    summary: string;
+    escalationReason?: string;
+    learningsExtracted?: boolean;
+}
+export type LeadPriority = "P0" | "P1" | "P2" | "P3";
+export type LeadComplexityHint = "small" | "medium" | "large";
+export interface ExternalTask {
+    taskId: string;
+    sessionUuid: string;
+    cwd: string;
+    pluginDirs: string[];
+    parentTaskId?: string;
+    parentSessionUuid?: string;
+    state: ExternalTaskState;
+    title: string;
+    /**
+     * v2 — iterate 3 section 02. ADR-037. Always a non-empty string; the
+     * reserved literal UNASSIGNED_PROJECT_ID represents tasks without a
+     * chosen project (and deleted-project references resolved via O26).
+     * v1 rows on disk are backfilled with UNASSIGNED_PROJECT_ID at load time.
+     */
+    projectId: string;
+    /**
+     * 2026-04-23 — captured at /launch time when NewIssueModal passes the
+     * full action context. All five fields are optional so legacy rows
+     * (pre-launch-wiring, back-compat test path, or manual API callers
+     * that skip the new payload) keep loading cleanly. The launch route
+     * persists them AFTER successful substitutePlaceholders — if the
+     * substitution throws (unknown phase, newline in title or a parameter),
+     * nothing is persisted.
+     *
+     * 2026-04-25 — iterate-custom-actions-generic-mode. Type widened from a
+     * 4-id union to `string` so user-defined actions in `.shipwright-webui/actions.json`
+     * (e.g. `new-content-orchestrator`) can flow through. Catalog membership
+     * is the validity gate at /launch time — see routes.ts `unknown_action_id`.
+     */
+    actionId?: string;
+    phase?: string;
+    phaseLabel?: string;
+    description?: string;
+    autonomy?: "guided" | "autonomous";
+    /**
+     * v3 — iterate/multi-session-run-orchestrator-v2. Optional linkage to
+     * a framework run-config v2 phase_task. When set, this task is a
+     * "shadow" of an external multi-session phase the user is running.
+     * - phaseTaskId   — the orchestrator's `phaseTaskId` (ptk-...)
+     * - runId         — the owning run (run-XXXXXXXX)
+     * - parentRunMaster — true if the shadow represents the master
+     *   conversation (always false in this iterate; reserved for future).
+     * Idempotency: the create-task route looks up existing tasks by
+     * phaseTaskId before inserting; multiple Continue Pipeline clicks
+     * for the same phase_task reuse the existing shadow.
+     */
+    phaseTaskId?: string;
+    runId?: string;
+    parentRunMaster?: boolean;
+    /**
+     * iterate-2026-05-14 lead-foundation-task-schema — leadwright Phase 1.
+     * All additive + optional; the persisted shape writes only keys that are
+     * set, and the loader soft-drops malformed values per-field (mirrors the
+     * phaseTaskId / runId / parentRunMaster forward-compat tolerance).
+     * User-creatable via POST: domain, priority, complexityHint, tags,
+     * blockedBy, leadParentTaskId. PATCH-only: poFeedback. Daemon-owned
+     * (MED-4 in routes.ts): claimToken, claimedBy, claimedAt, claimPid, leadHandoff, promotedFromTriageId.
+     */
+    domain?: string;
+    priority?: LeadPriority;
+    complexityHint?: LeadComplexityHint;
+    tags?: string[];
+    blockedBy?: string[];
+    leadParentTaskId?: string;
+    poFeedback?: string;
+    claimToken?: string;
+    claimedBy?: string;
+    claimedAt?: string;
+    claimPid?: number;
+    leadHandoff?: LeadHandoff;
+    promotedFromTriageId?: string;
+    /** v4 — sticky user-owned board-column override (write-on-touch). */
+    boardColumn?: BoardColumn;
+    /** S1 — durable iterate association (see mission-context/association.ts); NOT `runId`. */
+    missionContext?: MissionContextAssociation;
+    createdAt: string;
+    launchedAt?: string;
+    firstJsonlObservedAt?: string;
+    lastJsonlSeenMtimeMs?: number;
+    inbox: ExternalTaskInboxState;
+}
+export interface SdkSessionsFile {
+    schemaVersion: 1 | 2 | 3 | 4;
+    sessions: Record<string, ExternalTask>;
+}
+export interface SdkSessionsStoreDeps {
+    readFile: (path: string, encoding: string) => Promise<string>;
+    writeFile: (path: string, data: string) => Promise<void>;
+    existsSync: (path: string) => boolean;
+    mkdirSync: (path: string, opts?: {
+        recursive: boolean;
+    }) => void;
+    /** Optional proper-lockfile wrapper; omitted in tests. */
+    lock?: (path: string) => Promise<() => Promise<void>>;
+    /** Creates an empty file if missing (proper-lockfile requires lstat). */
+    ensureFile: (path: string) => void;
+    /** Optional atomic rename (default `fs.promises.rename`); omitted in unit doubles. */
+    rename?: (from: string, to: string) => Promise<void>;
+    /**
+     * Optional — section 02 O26. If provided, v2-loaded rows whose
+     * projectId is not in this set are resolved to UNASSIGNED_PROJECT_ID
+     * in memory. Next persist() writes the canonical value back.
+     * Omitted in unit tests (skips the resolve step).
+     */
+    getKnownProjectIds?: () => Set<string>;
+}
+export declare class SdkSessionsStore {
+    private readonly path;
+    private readonly deps;
+    private sessions;
+    /** Deep-copy of `sessions` at load()/last-persist — the 3-way merge base (F08). */
+    private baseline;
+    /** ids deleted since baseline — merge drops them so a delete beats disk churn (F08). */
+    private deletedSinceBaseline;
+    private loaded;
+    constructor(path: string, deps: SdkSessionsStoreDeps);
+    load(): Promise<void>;
+    create(args: {
+        title: string;
+        cwd: string;
+        pluginDirs?: string[];
+        parentTaskId?: string;
+        parentSessionUuid?: string;
+        /**
+         * v2 — iterate 3 section 02. Defaults to UNASSIGNED_PROJECT_ID when
+         * omitted. Callers that know the active project (e.g. the inline
+         * task-creation form on TaskBoardPage) pass it explicitly.
+         */
+        projectId?: string;
+        /**
+         * 2026-04-23 — iterate-20260423-chat-livetest-2 AC-B. Phase is
+         * validated by the route against the project's actions catalog
+         * BEFORE reaching this method; the label is derived server-side
+         * from the matched catalog entry. Both fields are optional so the
+         * legacy inline create flow + unassigned tasks still work.
+         */
+        phase?: string;
+        phaseLabel?: string;
+        /**
+         * 2026-05-05 — Save-to-Backlog wiring. Persisted at create-time so
+         * a later TaskCard "Launch" click on a draft task recovers the right
+         * command_template via routes.ts:421 fallback. The route validates
+         * catalog membership at /launch time (`unknown_action_id` 400).
+         */
+        actionId?: string;
+        /**
+         * v3 — iterate/multi-session-run-orchestrator-v2. When the caller
+         * passes a sessionUuid (Continue Pipeline path), it overrides the
+         * auto-generated one — the framework's orchestrator has pre-bound
+         * the uuid in run-config and the user's CLI launch must use it. The
+         * route validates the uuid format + that it matches a phase_task
+         * BEFORE calling here; this method trusts the caller.
+         */
+        sessionUuid?: string;
+        phaseTaskId?: string;
+        runId?: string;
+        parentRunMaster?: boolean;
+        /**
+         * iterate-2026-05-14 lead-foundation-task-schema, widened 2026-08-16 to
+         * 6 fields (+leadParentTaskId). Daemon-owned fields (`claimToken`,
+         * `leadHandoff`, etc.) stay unexposed here — the daemon mutates them via
+         * its own claim helper in the leadwright repo. External review MED-4.
+         */
+        domain?: string;
+        priority?: LeadPriority;
+        complexityHint?: LeadComplexityHint;
+        tags?: string[];
+        blockedBy?: string[];
+        leadParentTaskId?: string;
+        /**
+         * iterate-2026-05-14 triage-tab (ADR-101) — back-ref to the upstream
+         * triage item id (`trg-<8hex>`). Set EXCLUSIVELY by the
+         * `/api/triage/:projectId/promote` route. Public POST
+         * `/api/external/tasks` does NOT accept this field (narrow write
+         * surface, mirrors the ADR-100 MED-4 pattern for daemon-only fields).
+         */
+        promotedFromTriageId?: string;
+        /**
+         * iterate-2026-05-18-edit-task-dialog — the task brief / initial
+         * prompt. Previously only persisted by the /launch route; "Save to
+         * Backlog" dropped it entirely. The route trims + length-caps before
+         * calling here, so this method just stores whatever it is handed.
+         */
+        description?: string;
+    }): ExternalTask;
+    /**
+     * v3 — find an existing non-terminal task by `phaseTaskId`. Used by the
+     * create-task route to make Continue Pipeline launches idempotent: a second
+     * click on the same phase_task reuses the prior shadow (review O #6). Returns
+     * the first match (only one non-terminal shadow per phase_task; defensive).
+     */
+    findByPhaseTaskId(phaseTaskId: string): ExternalTask | undefined;
+    /**
+     * iterate-2026-05-14 triage-tab (ADR-101) — find an existing task by
+     * `promotedFromTriageId`. Used by the promote route to make
+     * Promote idempotent: if a previous attempt completed step 5 (created
+     * task) but step 7 (status flip) failed, the retry must NOT create
+     * another task — it must reuse the existing one and re-attempt the
+     * status flip. Mirrors the `findByPhaseTaskId` pattern.
+     *
+     * Includes done-state tasks too (unlike findByPhaseTaskId): a triage
+     * item promoted to a task that's been completed should still block
+     * a re-promote attempt; the back-ref is unique per triage id.
+     */
+    findByPromotedFromTriageId(triageId: string): ExternalTask | undefined;
+    get(taskId: string): ExternalTask | undefined;
+    list(): ExternalTask[];
+    /** Apply a partial patch to a task; returns the updated copy or undefined. */
+    patch(taskId: string, patch: Partial<ExternalTask>): ExternalTask | undefined;
+    delete(taskId: string): boolean;
+    /** Merge under the lock (F08 header note) + atomically flush. `await` after any mutation. */
+    persist(): Promise<void>;
+}
+//# sourceMappingURL=sdk-sessions-store.d.ts.map

package/server/dist/core/sdk-sessions-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-sessions-store.d.ts","sourceRoot":"","sources":["../../src/core/sdk-sessions-store.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAI5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,yBAAyB,GACzB,QAAQ,GACR,MAAM,GACN,eAAe,GACf,eAAe,GACf,MAAM,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,0FAMe,CAAC;AAElD,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAEtE;AAGD,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACrD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0FAA0F;IAC1F,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,sBAAsB,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACjE,0DAA0D;IAC1D,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,yEAAyE;IACzE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC;CACxC;AAID,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAmC;IACnD,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAmC;IACnD,wFAAwF;IACxF,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB;IAK9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4F3B,MAAM,CAAC,IAAI,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB;;;;;;WAMG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB;;;;;;;WAOG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B;;;;;WAKG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,cAAc,CAAC,EAAE,kBAAkB,CAAC;QACpC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B;;;;;;WAMG;QACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B;;;;;WAKG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,YAAY;IAoDhB;;;;;OAKG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAOhE;;;;;;;;;;;OAWG;IACH,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAOtE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7C,IAAI,IAAI,YAAY,EAAE;IAMtB,8EAA8E;IAC9E,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,GAAG,SAAS;IAO7E,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAS/B,6FAA6F;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA2C/B"}