workerstack 0.1.0-beta.0

package/dist/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AAsBjB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EACL,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAA","sourcesContent":["// src/jobs/index.ts — module surface consumed by workerstack.\nexport {\n  createJobsBuilder,\n  validateBackgroundDefs,\n  validateJobsDefs,\n  DEFAULT_RETRIES,\n  DEFAULT_LEASE_DURATION_MS,\n  DEFAULT_TIMEOUT_MS,\n  leaseDurationFor,\n} from './define'\nexport type {\n  AnyJobDefinition,\n  BackgroundTiming,\n  BackgroundDefinition,\n  BackgroundDefs,\n  WorkerstackJobContext,\n  WorkerstackJobsBuilder,\n  DedupeUntil,\n  EnqueueOptions,\n  EnqueueTransaction,\n  JobContext,\n  JobDefinition,\n  QueueJobDefinition,\n  CronDefinition,\n  CronInvocation,\n  QueueJobKeys,\n  TypedEnqueueOptions,\n  JobsDefs,\n  JobsFacade,\n  JobsRuntimeFacade,\n} from './define'\nexport { enqueueJob, enqueueTarget, resolveRunAt } from './queue'\nexport { createJobRunner } from './worker'\nexport { parseCron, cronMatches } from './cron'\nexport {\n  slotsDue,\n  floorSlot,\n  nextCronSlot,\n  CRON_PREFIX,\n  SLOT_MS,\n} from './slots'\nexport type { CatchUp } from './slots'\nexport type { TickResult } from './define'\n"]}

package/dist/jobs/queue.d.ts

@@ -0,0 +1,13 @@
+import type { AnyDb } from '../dialect.js';
+import type { EnqueueOptions, JobsDefs } from './define.js';
+/**
+ * The handle an enqueue inserts through: the caller's transaction when given,
+ * otherwise the app database. A transaction from an unrelated connection
+ * cannot be detected cheaply and is unsupported.
+ */
+export declare function enqueueTarget(db: AnyDb, tx: AnyDb | undefined): AnyDb;
+export declare function resolveRunAt(opts: EnqueueOptions, now: number): number;
+export declare function enqueueJob(db: AnyDb, defs: JobsDefs, name: string, input: unknown, opts?: EnqueueOptions, now?: number): Promise<{
+    id: string;
+}>;
+//# sourceMappingURL=queue.d.ts.map

package/dist/jobs/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/jobs/queue.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAOxD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG,SAAS,GAAG,KAAK,CAMrE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAItE;AAED,wBAAsB,UAAU,CAC9B,EAAE,EAAE,KAAK,EACT,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,cAAmB,EACzB,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CA6CzB"}

package/dist/jobs/queue.js

@@ -0,0 +1,71 @@
+// src/jobs/queue.ts — durable enqueue with constraint-backed dedupe.
+import { and, eq, is } from 'drizzle-orm';
+import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
+import { workerstackJobs } from '../internal-tables.js';
+import { validateStandardSchema } from '../standard-schema.js';
+import { generate } from '../typeid.js';
+import { CRON_PREFIX } from './slots.js';
+/**
+ * The handle an enqueue inserts through: the caller's transaction when given,
+ * otherwise the app database. A transaction from an unrelated connection
+ * cannot be detected cheaply and is unsupported.
+ */
+export function enqueueTarget(db, tx) {
+    if (tx === undefined)
+        return db;
+    if (!is(tx, BaseSQLiteDatabase)) {
+        throw new Error('[workerstack] enqueue tx is not a SQLite transaction');
+    }
+    return tx;
+}
+export function resolveRunAt(opts, now) {
+    return opts.runAt !== undefined
+        ? new Date(opts.runAt).getTime()
+        : now + (opts.delay ?? 0);
+}
+export async function enqueueJob(db, defs, name, input, opts = {}, now = Date.now()) {
+    const def = defs[name];
+    if (!def) {
+        throw new Error(`[workerstack] unknown background task "${name}"`);
+    }
+    const isCron = def.kind === 'cron';
+    const type = isCron ? `${CRON_PREFIX}${name}` : name;
+    // Cron slots carry no payload; queue jobs validate theirs at the call site.
+    const parsed = isCron
+        ? null
+        : def.input
+            ? validateStandardSchema(def.input, input, `job "${name}" input`)
+            : null;
+    const t = workerstackJobs;
+    const runAt = resolveRunAt(opts, now);
+    // Two rounds cover the race where the deduping row reaches a terminal state
+    // (clearing its key) between our failed insert and our read.
+    for (let round = 0; round < 2; round++) {
+        const id = generate('job');
+        const insertedRows = await db
+            .insert(t)
+            .values({
+            id,
+            type,
+            payloadJson: JSON.stringify(parsed),
+            status: 'pending',
+            attempts: 0,
+            runAt,
+            dedupeKey: opts.dedupeKey ?? null,
+            createdAt: now,
+        })
+            .onConflictDoNothing({ target: [t.type, t.dedupeKey] })
+            .returning({ id: t.id });
+        if (insertedRows[0])
+            return { id: String(insertedRows[0].id) };
+        const existing = await db
+            .select({ id: t.id })
+            .from(t)
+            .where(and(eq(t.type, type), eq(t.dedupeKey, opts.dedupeKey ?? '')))
+            .limit(1);
+        if (existing[0])
+            return { id: String(existing[0].id) };
+    }
+    throw new Error(`[workerstack] enqueue of "${name}" lost a dedupe race twice — please retry`);
+}
+//# sourceMappingURL=queue.js.map

package/dist/jobs/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/jobs/queue.ts"],"names":[],"mappings":"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","sourcesContent":["// src/jobs/queue.ts — durable enqueue with constraint-backed dedupe.\nimport { and, eq, is } from 'drizzle-orm'\nimport { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core'\n\nimport type { AnyDb } from '../dialect'\nimport type { EnqueueOptions, JobsDefs } from './define'\n\nimport { workerstackJobs } from '../internal-tables'\nimport { validateStandardSchema } from '../standard-schema'\nimport { generate } from '../typeid'\nimport { CRON_PREFIX } from './slots'\n\n/**\n * The handle an enqueue inserts through: the caller's transaction when given,\n * otherwise the app database. A transaction from an unrelated connection\n * cannot be detected cheaply and is unsupported.\n */\nexport function enqueueTarget(db: AnyDb, tx: AnyDb | undefined): AnyDb {\n  if (tx === undefined) return db\n  if (!is(tx, BaseSQLiteDatabase)) {\n    throw new Error('[workerstack] enqueue tx is not a SQLite transaction')\n  }\n  return tx\n}\n\nexport function resolveRunAt(opts: EnqueueOptions, now: number): number {\n  return opts.runAt !== undefined\n    ? new Date(opts.runAt).getTime()\n    : now + (opts.delay ?? 0)\n}\n\nexport async function enqueueJob(\n  db: AnyDb,\n  defs: JobsDefs,\n  name: string,\n  input: unknown,\n  opts: EnqueueOptions = {},\n  now: number = Date.now(),\n): Promise<{ id: string }> {\n  const def = defs[name]\n  if (!def) {\n    throw new Error(`[workerstack] unknown background task \"${name}\"`)\n  }\n  const isCron = def.kind === 'cron'\n  const type = isCron ? `${CRON_PREFIX}${name}` : name\n  // Cron slots carry no payload; queue jobs validate theirs at the call site.\n  const parsed = isCron\n    ? null\n    : def.input\n      ? validateStandardSchema(def.input, input, `job \"${name}\" input`)\n      : null\n  const t = workerstackJobs\n  const runAt = resolveRunAt(opts, now)\n\n  // Two rounds cover the race where the deduping row reaches a terminal state\n  // (clearing its key) between our failed insert and our read.\n  for (let round = 0; round < 2; round++) {\n    const id = generate('job')\n    const insertedRows = await db\n      .insert(t)\n      .values({\n        id,\n        type,\n        payloadJson: JSON.stringify(parsed),\n        status: 'pending',\n        attempts: 0,\n        runAt,\n        dedupeKey: opts.dedupeKey ?? null,\n        createdAt: now,\n      })\n      .onConflictDoNothing({ target: [t.type, t.dedupeKey] })\n      .returning({ id: t.id })\n    if (insertedRows[0]) return { id: String(insertedRows[0].id) }\n    const existing = await db\n      .select({ id: t.id })\n      .from(t)\n      .where(and(eq(t.type, type), eq(t.dedupeKey, opts.dedupeKey ?? '')))\n      .limit(1)\n    if (existing[0]) return { id: String(existing[0].id) }\n  }\n  throw new Error(\n    `[workerstack] enqueue of \"${name}\" lost a dedupe race twice — please retry`,\n  )\n}\n"]}

package/dist/jobs/slots.d.ts

@@ -0,0 +1,30 @@
+import { type ParsedCron } from './cron.js';
+/** Slot granularity. Every slot timestamp satisfies `slot % SLOT_MS === 0`. */
+export declare const SLOT_MS = 60000;
+/** Reserved job-type prefix for cron occurrences. */
+export declare const CRON_PREFIX = "cron:";
+/** How far back either catch-up mode will look. */
+export declare const DEFAULT_CATCH_UP_WINDOW_MS: number;
+export type CatchUp = 'latest' | 'all';
+/** Aligns `ms` down to its containing slot. */
+export declare function floorSlot(ms: number): number;
+/**
+ * Slots matching `cron` in the half-open range `(from, to]`, oldest first.
+ *
+ * `from` is exclusive so a stored watermark is never re-emitted. Both modes are
+ * clamped to `catchUpWindowMs` — without it a watermark far in the past would
+ * make this iterate unbounded minutes.
+ */
+export declare function slotsDue(args: {
+    cron: ParsedCron;
+    from: number;
+    to: number;
+    catchUp?: CatchUp;
+    catchUpWindowMs?: number;
+}): number[];
+/**
+ * The first slot matching `cron` in `(after, until]`, or null. A scheduler
+ * uses it to set its next alarm; `until` bounds the search.
+ */
+export declare function nextCronSlot(cron: ParsedCron, after: number, until: number): number | null;
+//# sourceMappingURL=slots.d.ts.map

package/dist/jobs/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/jobs/slots.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAA;AAErD,+EAA+E;AAC/E,eAAO,MAAM,OAAO,QAAS,CAAA;AAE7B,qDAAqD;AACrD,eAAO,MAAM,WAAW,UAAU,CAAA;AAElC,mDAAmD;AACnD,eAAO,MAAM,0BAA0B,QAAe,CAAA;AAEtD,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEtC,+CAA+C;AAC/C,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,IAAI,EAAE,UAAU,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,MAAM,EAAE,CAmBX;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAMf"}

package/dist/jobs/slots.js

@@ -0,0 +1,53 @@
+// src/jobs/slots.ts — cron slot enumeration. Pure; no db, no clock reads.
+import { cronMatches } from './cron.js';
+/** Slot granularity. Every slot timestamp satisfies `slot % SLOT_MS === 0`. */
+export const SLOT_MS = 60_000;
+/** Reserved job-type prefix for cron occurrences. */
+export const CRON_PREFIX = 'cron:';
+/** How far back either catch-up mode will look. */
+export const DEFAULT_CATCH_UP_WINDOW_MS = 60 * SLOT_MS;
+/** Aligns `ms` down to its containing slot. */
+export function floorSlot(ms) {
+    return Math.floor(ms / SLOT_MS) * SLOT_MS;
+}
+/**
+ * Slots matching `cron` in the half-open range `(from, to]`, oldest first.
+ *
+ * `from` is exclusive so a stored watermark is never re-emitted. Both modes are
+ * clamped to `catchUpWindowMs` — without it a watermark far in the past would
+ * make this iterate unbounded minutes.
+ */
+export function slotsDue(args) {
+    const catchUp = args.catchUp ?? 'latest';
+    const windowMs = args.catchUpWindowMs ?? DEFAULT_CATCH_UP_WINDOW_MS;
+    const to = floorSlot(args.to);
+    const from = Math.max(floorSlot(args.from), to - windowMs);
+    if (to <= from)
+        return [];
+    if (catchUp === 'latest') {
+        for (let s = to; s > from; s -= SLOT_MS) {
+            if (cronMatches(args.cron, s))
+                return [s];
+        }
+        return [];
+    }
+    const slots = [];
+    for (let s = from + SLOT_MS; s <= to; s += SLOT_MS) {
+        if (cronMatches(args.cron, s))
+            slots.push(s);
+    }
+    return slots;
+}
+/**
+ * The first slot matching `cron` in `(after, until]`, or null. A scheduler
+ * uses it to set its next alarm; `until` bounds the search.
+ */
+export function nextCronSlot(cron, after, until) {
+    const last = floorSlot(until);
+    for (let s = floorSlot(after) + SLOT_MS; s <= last; s += SLOT_MS) {
+        if (cronMatches(cron, s))
+            return s;
+    }
+    return null;
+}
+//# sourceMappingURL=slots.js.map

package/dist/jobs/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../src/jobs/slots.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAmB,MAAM,QAAQ,CAAA;AAErD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAA;AAE7B,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAA;AAElC,mDAAmD;AACnD,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,OAAO,CAAA;AAItD,+CAA+C;AAC/C,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,OAAO,CAAA;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAMxB;IACC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAA;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,IAAI,0BAA0B,CAAA;IACnE,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAA;IAC1D,IAAI,EAAE,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IAEzB,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;YACxC,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBAAE,OAAO,CAAC,CAAC,CAAC,CAAA;QAC3C,CAAC;QACD,OAAO,EAAE,CAAA;IACX,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;QACnD,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAgB,EAChB,KAAa,EACb,KAAa;IAEb,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC7B,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;QACjE,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;YAAE,OAAO,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["// src/jobs/slots.ts — cron slot enumeration. Pure; no db, no clock reads.\nimport { cronMatches, type ParsedCron } from './cron'\n\n/** Slot granularity. Every slot timestamp satisfies `slot % SLOT_MS === 0`. */\nexport const SLOT_MS = 60_000\n\n/** Reserved job-type prefix for cron occurrences. */\nexport const CRON_PREFIX = 'cron:'\n\n/** How far back either catch-up mode will look. */\nexport const DEFAULT_CATCH_UP_WINDOW_MS = 60 * SLOT_MS\n\nexport type CatchUp = 'latest' | 'all'\n\n/** Aligns `ms` down to its containing slot. */\nexport function floorSlot(ms: number): number {\n  return Math.floor(ms / SLOT_MS) * SLOT_MS\n}\n\n/**\n * Slots matching `cron` in the half-open range `(from, to]`, oldest first.\n *\n * `from` is exclusive so a stored watermark is never re-emitted. Both modes are\n * clamped to `catchUpWindowMs` — without it a watermark far in the past would\n * make this iterate unbounded minutes.\n */\nexport function slotsDue(args: {\n  cron: ParsedCron\n  from: number\n  to: number\n  catchUp?: CatchUp\n  catchUpWindowMs?: number\n}): number[] {\n  const catchUp = args.catchUp ?? 'latest'\n  const windowMs = args.catchUpWindowMs ?? DEFAULT_CATCH_UP_WINDOW_MS\n  const to = floorSlot(args.to)\n  const from = Math.max(floorSlot(args.from), to - windowMs)\n  if (to <= from) return []\n\n  if (catchUp === 'latest') {\n    for (let s = to; s > from; s -= SLOT_MS) {\n      if (cronMatches(args.cron, s)) return [s]\n    }\n    return []\n  }\n\n  const slots: number[] = []\n  for (let s = from + SLOT_MS; s <= to; s += SLOT_MS) {\n    if (cronMatches(args.cron, s)) slots.push(s)\n  }\n  return slots\n}\n\n/**\n * The first slot matching `cron` in `(after, until]`, or null. A scheduler\n * uses it to set its next alarm; `until` bounds the search.\n */\nexport function nextCronSlot(\n  cron: ParsedCron,\n  after: number,\n  until: number,\n): number | null {\n  const last = floorSlot(until)\n  for (let s = floorSlot(after) + SLOT_MS; s <= last; s += SLOT_MS) {\n    if (cronMatches(cron, s)) return s\n  }\n  return null\n}\n"]}

package/dist/jobs/worker.d.ts

@@ -0,0 +1,45 @@
+import type { AnyDb } from '../dialect.js';
+import type { WorkerstackLogger } from '../logging.js';
+import type { JobsDefs, JobsRuntimeFacade, TickResult } from './define.js';
+type PumpResult = {
+    wake?: Promise<void>;
+};
+export declare function createJobRunner(deps: {
+    db: AnyDb;
+    defs: JobsDefs;
+    /** Handler ctx WITHOUT `jobs`; the facade is injected via setJobsFacade. */
+    ctx: Record<string, unknown>;
+    logger?: WorkerstackLogger;
+}): {
+    tick(now?: number): Promise<TickResult>;
+    pump: (now?: number) => Promise<PumpResult>;
+    drain: () => Promise<void>;
+    /**
+     * The earliest time that has work: a pending run_at, a running lease end,
+     * or a cron slot not yet materialized. Never earlier than `now`; null when
+     * nothing is due before `until`.
+     */
+    nextDueAt(now: number, until: number): Promise<number | null>;
+    inspect(now: number): Promise<{
+        runnable: any;
+        failed: {
+            id: string;
+            name: string;
+            attempts: number;
+            lastError: string | null;
+        }[];
+        jobs: {
+            id: string;
+            name: string;
+            kind: "job" | "cron";
+            status: "pending" | "running" | "succeeded" | "failed";
+            attempts: number;
+            runAt: number;
+            dedupeKey: string | null;
+            lastError: string | null;
+        }[];
+    }>;
+    setJobsFacade(f: JobsRuntimeFacade): void;
+};
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/jobs/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAEV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACX,MAAM,UAAU,CAAA;AA2DjB,KAAK,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AA8D1C,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,EAAE,EAAE,KAAK,CAAA;IACT,IAAI,EAAE,QAAQ,CAAA;IACd,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B;eAggBmB,MAAM,GAAgB,OAAO,CAAC,UAAU,CAAC;iBAnBlC,MAAM,KAAgB,OAAO,CAAC,UAAU,CAAC;iBAa1C,OAAO,CAAC,IAAI,CAAC;IAYnC;;;;OAIG;mBACkB,MAAM,SAAS,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;iBAyBhD,MAAM;;;;;;;;;;;;oBAiEb,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ;;;;;;;qBAQH,iBAAiB;EAIrC"}