@ai-dossier/sched 0.2.0 → 0.3.0

package/dist/readiness.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Readiness: which units can run right now, as a pure function of state
+ * (RFC-0001 §E.4: "scheduler gates on merge" — an issue with an unmerged
+ * dependency is never runnable, and a batch is never dispatched while a batch
+ * it depends on is unmerged).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISPATCHABLE_ISSUE_STATUSES = void 0;
+exports.dependencyBlockers = dependencyBlockers;
+exports.batchBlockers = batchBlockers;
+exports.runnableUnits = runnableUnits;
+const state_1 = require("./state");
+const types_1 = require("./types");
+/** Issue statuses from which a full-cycle dispatch may start. */
+exports.DISPATCHABLE_ISSUE_STATUSES = new Set([
+    // `queued` is dispatchable because the manifest already carries the mode —
+    // the classifier (#465) only refines it later.
+    'queued',
+    'classified',
+    'requeued',
+]);
+function batchOf(state, issue) {
+    return state.batches.find((b) => b.members.includes(issue));
+}
+/**
+ * Unsatisfied dependency edges of a single entry. Deps satisfied by
+ * membership in the SAME batch are not blockers — intra-batch ordering is the
+ * batch's own concern once dispatched (RFC-0001 §E.4).
+ */
+function dependencyBlockers(state, entry) {
+    const blockers = [];
+    const ownBatch = entry.batch !== null ? (0, state_1.findBatch)(state, entry.batch) : undefined;
+    for (const dep of entry.deps) {
+        if (ownBatch?.members.includes(dep))
+            continue;
+        const depEntry = state.entries.find((e) => e.issue === dep);
+        if (!depEntry) {
+            blockers.push({ issue: entry.issue, dep, reason: 'not-in-queue' });
+            continue;
+        }
+        if (!types_1.SATISFIED_ISSUE_STATUSES.has(depEntry.status)) {
+            blockers.push({ issue: entry.issue, dep, reason: 'unmerged', depStatus: depEntry.status });
+        }
+    }
+    return blockers;
+}
+/** Whether `batch` may dispatch: status `ready` and every cross-batch/cross-issue edge merged. */
+function batchBlockers(state, batch) {
+    const blockers = [];
+    for (const member of batch.members) {
+        const entry = state.entries.find((e) => e.issue === member);
+        if (!entry)
+            continue; // validateState guarantees membership consistency
+        for (const dep of entry.deps) {
+            if (batch.members.includes(dep))
+                continue; // intra-batch edge
+            const depBatch = batchOf(state, dep);
+            if (depBatch && depBatch.id !== batch.id) {
+                if (!types_1.MERGED_BATCH_STATUSES.has(depBatch.status)) {
+                    blockers.push({ issue: member, dep, reason: 'unmerged' });
+                }
+                continue;
+            }
+            const depEntry = state.entries.find((e) => e.issue === dep);
+            if (!depEntry) {
+                blockers.push({ issue: member, dep, reason: 'not-in-queue' });
+            }
+            else if (!types_1.SATISFIED_ISSUE_STATUSES.has(depEntry.status)) {
+                blockers.push({ issue: member, dep, reason: 'unmerged', depStatus: depEntry.status });
+            }
+        }
+    }
+    return blockers;
+}
+/**
+ * All runnable units in stable dispatch order: issues in queue order, then
+ * batches in creation order. A batch unit unlocks ALL its members' execution,
+ * so batches are listed after issues only for stability — the caller slices to
+ * free capacity either way.
+ */
+function runnableUnits(state) {
+    const units = [];
+    for (const entry of state.entries) {
+        if (entry.mode !== 'full')
+            continue;
+        if (!exports.DISPATCHABLE_ISSUE_STATUSES.has(entry.status))
+            continue;
+        if (dependencyBlockers(state, entry).length > 0)
+            continue;
+        units.push({ kind: 'issue', issue: entry.issue });
+    }
+    for (const batch of state.batches) {
+        if (batch.status !== 'ready')
+            continue;
+        if (batchBlockers(state, batch).length > 0)
+            continue;
+        units.push({ kind: 'batch', batch: batch.id });
+    }
+    return units;
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

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

package/dist/scheduler.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The deterministic scheduler core: which units are runnable, and how idle
+ * slots get filled (RFC-0001 §B — "refill is a state-machine transition, not
+ * a remembered instruction").
+ *
+ * Everything here is a pure function of (state, config). Dispatching —
+ * spawning agent processes, completion verification, stall timers — is #464;
+ * this module only decides assignments and performs the typed slot/issue
+ * transitions that make them durable. When `state.paused` is set, no
+ * assignments are made at all (`sched pause`).
+ */
+import { batchBlockers, type DependencyBlocker, dependencyBlockers, type RunnableUnit, runnableUnits } from './readiness';
+import type { SchedConfig, SchedState } from './types';
+export { runnableUnits, dependencyBlockers, batchBlockers };
+export type { DependencyBlocker, RunnableUnit };
+/** One placement made by `computeAssignments`: slot ← unit. */
+export type Assignment = {
+    slot: number;
+    kind: 'issue';
+    issue: number;
+} | {
+    slot: number;
+    kind: 'batch';
+    batch: string;
+};
+/**
+ * Fill idle slots with runnable units, bounded by `config.max_slots` (AC5):
+ * `max_slots` caps LIVE slots (assigned | running | recovering), so free
+ * capacity = max_slots − live. Idle slots are reused first; new slots are
+ * materialized lazily (as `idle`, then transitioned `idle → assigned` — a
+ * typed edge, never a synthetic mid-state).
+ *
+ * `kinds` restricts which unit kinds may be assigned (default: both). The
+ * #464 engine dispatches `issue` units only — batch member sequencing is a
+ * follow-up — so it passes `['issue']` and a `ready` batch never occupies a
+ * slot it cannot run on yet.
+ */
+export declare function computeAssignments(state: SchedState, config: SchedConfig, now?: Date, kinds?: readonly ('issue' | 'batch')[]): {
+    state: SchedState;
+    assignments: Assignment[];
+};
+/** Free live-agent capacity: `max_slots` minus the slots holding live units (AC5). */
+export declare function freeCapacity(state: SchedState, config: SchedConfig): number;
+/**
+ * Assign `unit` to an idle slot (materializing one lazily when none is idle —
+ * a typed `idle → assigned` edge, never a synthetic mid-state) and return the
+ * new state plus the slot's id. Shared by queue refill (computeAssignments)
+ * and the #468 report dispatch so the slot-invariant shape exists once.
+ */
+export declare function assignToIdleSlot(state: SchedState, unit: string, phase: string | null, now: Date): {
+    state: SchedState;
+    slotId: number;
+};
+/**
+ * `sched pause` / `sched resume`: toggle the paused flag. Pausing does not
+ * touch live units — it only stops new assignments.
+ */
+export declare function setPaused(state: SchedState, paused: boolean): SchedState;
+/**
+ * `sched abandon --issue N`: mark an entry failed via the universal failure
+ * edge, recording the reason, and release any slot holding it
+ * (running/exited/verifying → failed → idle). Terminal entries cannot be
+ * abandoned.
+ */
+export declare function abandonIssue(state: SchedState, issue: number, reason?: string, now?: Date): {
+    state: SchedState;
+    releasedSlots: number[];
+};
+/**
+ * `sched abandon --batch B`: dissolve the batch and requeue every non-terminal
+ * member as full-cycle (RFC-0001 §D.2 dissolving → "members requeued"; F.8
+ * "nothing green is discarded" — members already shipped stay put).
+ */
+export declare function abandonBatch(state: SchedState, batchId: string, reason?: string, now?: Date): {
+    state: SchedState;
+    requeued: number[];
+};
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,kBAAkB,EAClB,KAAK,YAAY,EACjB,aAAa,EACd,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AASvD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,CAAC;AAEhD,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAMnD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,GAAG,GAAE,IAAiB,EACtB,KAAK,GAAE,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC,EAAuB,GACzD;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CA+BlD;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAG3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,IAAI,GACR;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAiCvC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,SAAc,EACpB,GAAG,GAAE,IAAiB,GACrB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAqBhD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,SAAoB,EAC1B,GAAG,GAAE,IAAiB,GACrB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA+C3C"}

package/dist/scheduler.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * The deterministic scheduler core: which units are runnable, and how idle
+ * slots get filled (RFC-0001 §B — "refill is a state-machine transition, not
+ * a remembered instruction").
+ *
+ * Everything here is a pure function of (state, config). Dispatching —
+ * spawning agent processes, completion verification, stall timers — is #464;
+ * this module only decides assignments and performs the typed slot/issue
+ * transitions that make them durable. When `state.paused` is set, no
+ * assignments are made at all (`sched pause`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchBlockers = exports.dependencyBlockers = exports.runnableUnits = void 0;
+exports.computeAssignments = computeAssignments;
+exports.freeCapacity = freeCapacity;
+exports.assignToIdleSlot = assignToIdleSlot;
+exports.setPaused = setPaused;
+exports.abandonIssue = abandonIssue;
+exports.abandonBatch = abandonBatch;
+const readiness_1 = require("./readiness");
+Object.defineProperty(exports, "batchBlockers", { enumerable: true, get: function () { return readiness_1.batchBlockers; } });
+Object.defineProperty(exports, "dependencyBlockers", { enumerable: true, get: function () { return readiness_1.dependencyBlockers; } });
+Object.defineProperty(exports, "runnableUnits", { enumerable: true, get: function () { return readiness_1.runnableUnits; } });
+const state_1 = require("./state");
+const types_1 = require("./types");
+function unitId(unit) {
+    return unit.kind === 'issue' ? `issue:${unit.issue}` : `batch:${unit.batch}`;
+}
+/**
+ * Fill idle slots with runnable units, bounded by `config.max_slots` (AC5):
+ * `max_slots` caps LIVE slots (assigned | running | recovering), so free
+ * capacity = max_slots − live. Idle slots are reused first; new slots are
+ * materialized lazily (as `idle`, then transitioned `idle → assigned` — a
+ * typed edge, never a synthetic mid-state).
+ *
+ * `kinds` restricts which unit kinds may be assigned (default: both). The
+ * #464 engine dispatches `issue` units only — batch member sequencing is a
+ * follow-up — so it passes `['issue']` and a `ready` batch never occupies a
+ * slot it cannot run on yet.
+ */
+function computeAssignments(state, config, now = new Date(), kinds = ['issue', 'batch']) {
+    if (state.paused) {
+        return { state, assignments: [] };
+    }
+    if (freeCapacity(state, config) === 0) {
+        return { state, assignments: [] };
+    }
+    const held = new Set(state.slots.map((s) => s.unit).filter((u) => u !== null));
+    const candidates = (0, readiness_1.runnableUnits)(state)
+        .filter((unit) => kinds.includes(unit.kind))
+        .filter((unit) => !held.has(unitId(unit)));
+    const taken = candidates.slice(0, freeCapacity(state, config));
+    if (taken.length === 0) {
+        return { state, assignments: [] };
+    }
+    let next = state;
+    const assignments = [];
+    for (const unit of taken) {
+        const assigned = assignToIdleSlot(next, unitId(unit), null, now);
+        next = assigned.state;
+        assignments.push(unit.kind === 'issue'
+            ? { slot: assigned.slotId, kind: 'issue', issue: unit.issue }
+            : { slot: assigned.slotId, kind: 'batch', batch: unit.batch });
+    }
+    return { state: next, assignments };
+}
+/** Free live-agent capacity: `max_slots` minus the slots holding live units (AC5). */
+function freeCapacity(state, config) {
+    const live = state.slots.filter((s) => types_1.LIVE_SLOT_STATUSES.has(s.status)).length;
+    return Math.max(0, config.max_slots - live);
+}
+/**
+ * Assign `unit` to an idle slot (materializing one lazily when none is idle —
+ * a typed `idle → assigned` edge, never a synthetic mid-state) and return the
+ * new state plus the slot's id. Shared by queue refill (computeAssignments)
+ * and the #468 report dispatch so the slot-invariant shape exists once.
+ */
+function assignToIdleSlot(state, unit, phase, now) {
+    let next = state;
+    let idle = next.slots.find((s) => s.status === 'idle');
+    if (!idle) {
+        const slot = {
+            id: next.next_slot_id,
+            status: 'idle',
+            unit: null,
+            pid: null,
+            pid_start: null,
+            phase: null,
+            last_progress_at: null,
+            branch: null,
+            last_head: null,
+            recoveries: 0,
+            updated_at: now.toISOString(),
+        };
+        next = { ...next, slots: [...next.slots, slot], next_slot_id: next.next_slot_id + 1 };
+        idle = slot;
+    }
+    next = (0, state_1.transitionSlot)(next, idle.id, 'assigned', {
+        unit,
+        pid: null,
+        phase,
+        last_progress_at: now.toISOString(),
+    }, now);
+    return { state: next, slotId: idle.id };
+}
+/**
+ * `sched pause` / `sched resume`: toggle the paused flag. Pausing does not
+ * touch live units — it only stops new assignments.
+ */
+function setPaused(state, paused) {
+    return { ...state, paused };
+}
+/**
+ * `sched abandon --issue N`: mark an entry failed via the universal failure
+ * edge, recording the reason, and release any slot holding it
+ * (running/exited/verifying → failed → idle). Terminal entries cannot be
+ * abandoned.
+ */
+function abandonIssue(state, issue, reason = 'abandoned', now = new Date()) {
+    const entry = state.entries.find((e) => e.issue === issue);
+    if (!entry) {
+        throw new types_1.SchedNotFoundError(`Queue entry not found: ${issue}`);
+    }
+    if (types_1.TERMINAL_ISSUE_STATUSES.has(entry.status)) {
+        throw new types_1.SchedNotFoundError(`Issue ${issue} is already ${entry.status} — nothing to abandon`);
+    }
+    let next = (0, state_1.transitionIssue)(state, issue, 'failed', { reason }, now);
+    const unit = `issue:${issue}`;
+    const released = [];
+    for (const slot of next.slots) {
+        if (slot.unit === unit && slot.status !== 'idle') {
+            if (slot.status !== 'failed' && slot.status !== 'complete') {
+                next = (0, state_1.transitionSlot)(next, slot.id, 'failed', {}, now);
+            }
+            next = (0, state_1.transitionSlot)(next, slot.id, 'idle', {}, now);
+            released.push(slot.id);
+        }
+    }
+    return { state: next, releasedSlots: released };
+}
+/**
+ * `sched abandon --batch B`: dissolve the batch and requeue every non-terminal
+ * member as full-cycle (RFC-0001 §D.2 dissolving → "members requeued"; F.8
+ * "nothing green is discarded" — members already shipped stay put).
+ */
+function abandonBatch(state, batchId, reason = 'batch abandoned', now = new Date()) {
+    const batch = (0, state_1.findBatch)(state, batchId);
+    if (!batch) {
+        throw new types_1.SchedNotFoundError(`Batch not found: ${batchId}`);
+    }
+    if (types_1.TERMINAL_BATCH_STATUSES.has(batch.status)) {
+        throw new types_1.SchedNotFoundError(`Batch ${batchId} is already ${batch.status} — nothing to abandon`);
+    }
+    let next = (0, state_1.transitionBatch)(state, batchId, 'dissolving', {}, now);
+    next = (0, state_1.transitionBatch)(next, batchId, 'dissolved', {}, now);
+    const requeued = [];
+    for (const issue of batch.members) {
+        const entry = next.entries.find((e) => e.issue === issue);
+        if (!entry)
+            continue;
+        // Nothing green is discarded (F.8): terminal or already-shipped members
+        // keep their outcome; only active members requeue.
+        if (types_1.TERMINAL_ISSUE_STATUSES.has(entry.status) || types_1.SATISFIED_ISSUE_STATUSES.has(entry.status)) {
+            continue;
+        }
+        if (entry.status === 'queued' || entry.status === 'classified') {
+            // Never reached the batch rail — retag as full-cycle (metadata change,
+            // not a status transition) and it stays queued as-is.
+            next = {
+                ...next,
+                entries: next.entries.map((e) => e.issue === issue
+                    ? { ...e, mode: 'full', batch: null, reason, updated_at: now.toISOString() }
+                    : e),
+            };
+            requeued.push(issue);
+            continue;
+        }
+        if (entry.status === 'evicted' || entry.status === 'requeued') {
+            next = (0, state_1.transitionIssue)(next, issue, 'requeued', { mode: 'full', batch: null, reason }, now);
+            requeued.push(issue);
+            continue;
+        }
+        // Any other active state: force onto the failure rail (evicted → requeued{full}).
+        next = (0, state_1.transitionIssue)(next, issue, 'evicted', { reason }, now);
+        next = (0, state_1.transitionIssue)(next, issue, 'requeued', { mode: 'full', batch: null, reason }, now);
+        requeued.push(issue);
+    }
+    return { state: next, requeued };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

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

package/dist/state.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure state machines for the scheduler core — RFC-0001 §D as explicit typed
+ * transitions. Every function here is pure: it takes a state and returns a new
+ * state (immutable spreads, like `packages/worktree-pool/src/pool-state.ts`),
+ * and every edge NOT in the tables throws `IllegalTransitionError` (AC3).
+ *
+ * Failure edges: RFC-0001 §D.1 states "any → blocked(dep-failed) |
+ * decision-pending | failed(escalation-cap)" — encoded generically for every
+ * non-terminal issue status rather than repeated per row.
+ */
+import { type BatchEntry, type BatchStatus, type IssueStatus, type QueueEntry, type SchedState, type SlotEntry, type SlotStatus } from './types';
+/** An empty state carries no timestamps — nothing exists yet to stamp. */
+export declare function createEmptyState(): SchedState;
+/**
+ * Strict validation of persisted state (mirrors pool-state's `validateState`):
+ * wrong schema version or malformed shape throws instead of being coerced, so
+ * a corrupt file is a loud failure, never a silent queue reset.
+ *
+ * Legacy schema versions are accepted and migrated: 1.0.0 (pre-#464) slots
+ * backfill `branch`/`last_head` to null; 1.1.0 (pre-#468) entries backfill
+ * `pr`/`cleanup` and the state backfills `last_pr_poll_at` to null. The state
+ * upgrades to the current schema on the next save.
+ */
+export declare function validateState(data: unknown): SchedState;
+export declare function transitionIssue(state: SchedState, issue: number, to: IssueStatus, patch?: Partial<QueueEntry>, now?: Date): SchedState;
+export declare function transitionBatch(state: SchedState, batchId: string, to: BatchStatus, patch?: Partial<BatchEntry>, now?: Date): SchedState;
+export declare function transitionSlot(state: SchedState, slotId: number, to: SlotStatus, patch?: Partial<SlotEntry>, now?: Date): SchedState;
+export declare function findEntry(state: SchedState, issue: number): QueueEntry | undefined;
+export declare function findBatch(state: SchedState, batchId: string): BatchEntry | undefined;
+/**
+ * All transition tables, exposed as public API — future consumers (#464's
+ * dispatcher, status previews) render next-state choices from here instead of
+ * re-deriving the RFC tables.
+ */
+export declare const TRANSITIONS: {
+    issue: (from: IssueStatus) => IssueStatus[];
+    batch: (from: BatchStatus) => BatchStatus[];
+    slot: (from: SlotStatus) => SlotStatus[];
+};
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,WAAW,EAEhB,KAAK,UAAU,EAGf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EAEhB,MAAM,SAAS,CAAC;AAsGjB,0EAA0E;AAC1E,wBAAgB,gBAAgB,IAAI,UAAU,CAU7C;AAyDD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAgKvD;AA0BD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,WAAW,EACf,KAAK,GAAE,OAAO,CAAC,UAAU,CAAM,EAC/B,GAAG,GAAE,IAAiB,GACrB,UAAU,CAeZ;AAID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,WAAW,EACf,KAAK,GAAE,OAAO,CAAC,UAAU,CAAM,EAC/B,GAAG,GAAE,IAAiB,GACrB,UAAU,CAeZ;AAID,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,UAAU,EACd,KAAK,GAAE,OAAO,CAAC,SAAS,CAAM,EAC9B,GAAG,GAAE,IAAiB,GACrB,UAAU,CAoBZ;AAID,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAElF;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEpF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW;kBACR,WAAW;kBACX,WAAW;iBACZ,UAAU;CACxB,CAAC"}