@ultimat3/jobs 1.0.0

package/src/limits.d.ts

@@ -0,0 +1,47 @@
+import type { Clock } from '@ultimat3/core';
+export interface RateLimit {
+    readonly limit: number;
+    readonly windowMs: number;
+}
+export interface LimitConfig {
+    /** Max concurrent runs per tenant, across every queue. */
+    readonly perTenant?: number;
+    /** Max concurrent runs per queue, across every tenant. */
+    readonly perQueue?: number;
+    /** Fleet-wide ceiling for this worker process. */
+    readonly global?: number;
+    /** Starts per tenant per window — protects downstream APIs, not just CPU. */
+    readonly ratePerTenant?: RateLimit;
+}
+export interface LimitKey {
+    readonly queue: string;
+    readonly tenantId?: string;
+}
+/** Returned on success; `release()` is idempotent so a double-release cannot leak slots. */
+export interface Lease {
+    readonly queue: string;
+    readonly tenantId: string;
+    release(): void;
+}
+export type LimitReason = 'per-tenant' | 'per-queue' | 'global' | 'rate';
+export interface LimitSnapshot {
+    readonly global: number;
+    readonly byQueue: Readonly<Record<string, number>>;
+    readonly byTenant: Readonly<Record<string, number>>;
+    readonly config: LimitConfig;
+}
+export interface Limiter {
+    /** `undefined` means "over a limit" — the claim loop leaves the job for another worker. */
+    tryAcquire(key: LimitKey): Lease | undefined;
+    /** Which limit blocked the last refusal for this key, for `/_x` and logs. */
+    blockedBy(key: LimitKey): LimitReason | undefined;
+    inFlight(key?: LimitKey): number;
+    snapshot(): LimitSnapshot;
+}
+export declare const NO_TENANT = "global";
+/** Tenant key resolution. Structural on purpose: `jobs` must not import the auth types. */
+export declare function tenantKeyFrom(actor: {
+    readonly orgId?: string;
+} | undefined): string;
+export declare function createLimiter(config: LimitConfig, clock?: Clock): Limiter;
+//# sourceMappingURL=limits.d.ts.map

package/src/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["limits.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,4FAA4F;AAC5F,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,OAAO;IACtB,2FAA2F;IAC3F,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAC7C,6EAA6E;IAC7E,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACjC,QAAQ,IAAI,aAAa,CAAC;CAC3B;AAED,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,MAAM,CAEpF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,GAAE,KAAmB,GAAG,OAAO,CAoFtF"}

package/src/limits.js.map

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

package/src/outbox.d.ts

@@ -0,0 +1,81 @@
+import type { Clock } from '@ultimat3/core';
+import type { Tx } from '@ultimat3/entity';
+import type { EnqueueResult, JobDriver } from './driver';
+import type { JobHandle } from './job';
+export interface OutboxRecord {
+    readonly id: string;
+    readonly job: string;
+    readonly queue: string;
+    readonly input: unknown;
+    readonly idempotencyKey: string;
+    readonly maxAttempts: number;
+    readonly runAt: number;
+    readonly stagedAt: number;
+    readonly tenantId?: string;
+    readonly publishedAt?: number;
+}
+export interface OutboxStore {
+    /** Write inside `tx`. Nothing is visible to the relay until that tx commits. */
+    stage(tx: Tx, record: OutboxRecord): Promise<void>;
+    /** Called by the tx runner after COMMIT. */
+    commit(tx: Tx): Promise<readonly OutboxRecord[]>;
+    /** Called by the tx runner after ROLLBACK. Staged rows vanish with the transaction. */
+    rollback(tx: Tx): Promise<void>;
+    /** Unpublished, committed rows — the relay's work queue. */
+    claim(limit: number): Promise<readonly OutboxRecord[]>;
+    markPublished(id: string, at: number): Promise<void>;
+    pendingCount(): Promise<number>;
+}
+/**
+ * Default store. Staged rows hang off the `Tx` object itself in a WeakMap, so the "same
+ * transaction" guarantee needs no cooperation from the DB layer and rollback is a delete.
+ * The pg store swaps this for a real `x_outbox` table written by the same connection.
+ */
+export declare function createMemoryOutboxStore(): OutboxStore;
+export interface EnqueueOptions {
+    /** Epoch ms, or a delay via `runAt: nowMs() + toMs('5m')`. */
+    readonly runAt?: number;
+    readonly tenantId?: string;
+    readonly queue?: string;
+    /** Escape hatch for enqueues that must fire regardless of the caller's transaction. */
+    readonly outbox?: boolean;
+}
+export interface OutboxDeps {
+    readonly store: OutboxStore;
+    readonly driver: JobDriver;
+    readonly clock?: Clock;
+    /** `'required'` fails an out-of-transaction enqueue instead of publishing it directly. */
+    readonly mode?: 'default' | 'required';
+}
+/** Stage a job inside `tx`. Returns the row that the relay will publish after commit. */
+export declare function enqueueInTx<I>(deps: OutboxDeps, tx: Tx, handle: JobHandle<I>, input: I, options?: EnqueueOptions): Promise<OutboxRecord>;
+export interface JobsFacade {
+    /**
+     * Joins the ambient transaction when there is one. Same call site in a request handler,
+     * a job, or a script — the transactional behaviour is the framework's problem, not yours.
+     */
+    enqueue<I>(handle: JobHandle<I>, input: I, options?: EnqueueOptions): Promise<EnqueueResult>;
+}
+export declare function createJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefined): JobsFacade;
+export interface RelayOptions extends OutboxDeps {
+    readonly batchSize?: number;
+    readonly intervalMs?: number;
+}
+export interface OutboxRelay {
+    /** One pass. Returns how many rows were published. Call it directly in tests. */
+    tick(): Promise<number>;
+    start(): void;
+    stop(): void;
+    pending(): Promise<number>;
+}
+/**
+ * At-least-once by construction: publish, THEN mark published. A crash between the two
+ * re-publishes, which the idempotency key collapses — the opposite order would lose jobs.
+ */
+export declare function createOutboxRelay(options: RelayOptions): OutboxRelay;
+/** SQL for the pg-backed outbox. The relay publishes rows this INSERT created. */
+export declare const SQL_OUTBOX_TABLE: string;
+export declare const SQL_OUTBOX_STAGE: string;
+export declare const SQL_OUTBOX_CLAIM: string;
+export declare const SQL_OUTBOX_MARK_PUBLISHED: string;
+//# sourceMappingURL=outbox.d.ts.map

package/src/outbox.d.ts.map

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

package/src/outbox.js

@@ -0,0 +1,202 @@
+// The transactional outbox — ON BY DEFAULT, because the alternative is a bug you cannot see
+// in review. `ctx.jobs.enqueue()` inside a request writes the job row in the SAME `tx` as the
+// business rows and a relay publishes it after commit. Without it, every enqueue is a
+// distributed-transaction coin flip:
+//
+//   enqueue then rollback  -> the job runs against rows that never existed
+//   commit then enqueue    -> the process dies in between and the job is lost forever
+//
+// Both are load-dependent, both pass every test, and both are the top source of "the email
+// went out but the order isn't in the database" tickets. Joining the transaction removes the
+// window entirely; the relay's at-least-once delivery is deduped by the job's idempotencyKey.
+import { logger, uuid } from '@ultimat3/core';
+import { nowMs } from './clock';
+import { DEFAULT_QUEUE } from './driver';
+import { OutboxNoTxError } from './errors';
+/**
+ * Default store. Staged rows hang off the `Tx` object itself in a WeakMap, so the "same
+ * transaction" guarantee needs no cooperation from the DB layer and rollback is a delete.
+ * The pg store swaps this for a real `x_outbox` table written by the same connection.
+ */
+export function createMemoryOutboxStore() {
+    const staged = new WeakMap();
+    const committed = new Map();
+    const key = (tx) => tx;
+    return {
+        stage(tx, record) {
+            const bucket = staged.get(key(tx)) ?? [];
+            bucket.push(record);
+            staged.set(key(tx), bucket);
+            return Promise.resolve();
+        },
+        commit(tx) {
+            const bucket = staged.get(key(tx)) ?? [];
+            staged.delete(key(tx));
+            for (const record of bucket)
+                committed.set(record.id, record);
+            return Promise.resolve(bucket);
+        },
+        rollback(tx) {
+            staged.delete(key(tx));
+            return Promise.resolve();
+        },
+        claim(limit) {
+            const ready = [...committed.values()]
+                .filter((record) => record.publishedAt === undefined)
+                .sort((a, b) => a.stagedAt - b.stagedAt)
+                .slice(0, limit);
+            return Promise.resolve(ready);
+        },
+        markPublished(id, at) {
+            const record = committed.get(id);
+            if (record !== undefined)
+                committed.set(id, { ...record, publishedAt: at });
+            return Promise.resolve();
+        },
+        pendingCount() {
+            let count = 0;
+            for (const record of committed.values()) {
+                if (record.publishedAt === undefined)
+                    count += 1;
+            }
+            return Promise.resolve(count);
+        },
+    };
+}
+/** Stage a job inside `tx`. Returns the row that the relay will publish after commit. */
+export function enqueueInTx(deps, tx, handle, input, options = {}) {
+    const at = nowMs(deps.clock);
+    const record = {
+        id: uuid(),
+        job: handle.name,
+        queue: options.queue ?? handle.queue ?? DEFAULT_QUEUE,
+        input,
+        idempotencyKey: handle.idempotencyKeyFor(input),
+        maxAttempts: handle.retry.attempts,
+        runAt: options.runAt ?? at,
+        stagedAt: at,
+        ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
+    };
+    return deps.store.stage(tx, record).then(() => record);
+}
+const STAGED_RESULT = { id: '', runId: '', deduped: false };
+export function createJobsFacade(deps, currentTx) {
+    return {
+        async enqueue(handle, input, options = {}) {
+            const tx = options.outbox === false ? undefined : currentTx();
+            if (tx === undefined) {
+                if (deps.mode === 'required' && options.outbox !== false) {
+                    throw new OutboxNoTxError({ job: handle.name });
+                }
+                return deps.driver.enqueue({
+                    name: handle.name,
+                    queue: options.queue ?? handle.queue,
+                    input,
+                    idempotencyKey: handle.idempotencyKeyFor(input),
+                    maxAttempts: handle.retry.attempts,
+                    runAt: options.runAt ?? nowMs(deps.clock),
+                    ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
+                });
+            }
+            const record = await enqueueInTx(deps, tx, handle, input, options);
+            // No queue id yet by design: the row does not exist until COMMIT.
+            return { ...STAGED_RESULT, id: record.id };
+        },
+    };
+}
+/**
+ * At-least-once by construction: publish, THEN mark published. A crash between the two
+ * re-publishes, which the idempotency key collapses — the opposite order would lose jobs.
+ */
+export function createOutboxRelay(options) {
+    const batchSize = options.batchSize ?? 100;
+    const intervalMs = options.intervalMs ?? 200;
+    let timer;
+    let running = false;
+    const tick = async () => {
+        const batch = await options.store.claim(batchSize);
+        let published = 0;
+        for (const record of batch) {
+            try {
+                await options.driver.enqueue({
+                    name: record.job,
+                    queue: record.queue,
+                    input: record.input,
+                    idempotencyKey: record.idempotencyKey,
+                    maxAttempts: record.maxAttempts,
+                    runAt: record.runAt,
+                    ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+                });
+                await options.store.markPublished(record.id, nowMs(options.clock));
+                published += 1;
+            }
+            catch (error) {
+                // Leave the row unpublished; the next tick retries it. Order is preserved per queue.
+                logger.warn('jobs.outbox.publish-failed', {
+                    job: record.job,
+                    id: record.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return published;
+    };
+    return {
+        tick,
+        start() {
+            if (timer !== undefined)
+                return;
+            timer = setInterval(() => {
+                if (running)
+                    return;
+                running = true;
+                void tick().finally(() => {
+                    running = false;
+                });
+            }, intervalMs);
+        },
+        stop() {
+            if (timer !== undefined)
+                clearInterval(timer);
+            timer = undefined;
+        },
+        pending: () => options.store.pendingCount(),
+    };
+}
+/** SQL for the pg-backed outbox. The relay publishes rows this INSERT created. */
+export const SQL_OUTBOX_TABLE = `
+create table if not exists x_outbox (
+  id              uuid primary key,
+  job             text        not null,
+  queue           text        not null default 'default',
+  input           jsonb       not null,
+  idempotency_key text        not null,
+  max_attempts    int         not null default 3,
+  run_at          timestamptz not null default now(),
+  staged_at       timestamptz not null default now(),
+  tenant_id       text,
+  published_at    timestamptz
+);
+create index if not exists x_outbox_unpublished_idx
+  on x_outbox (staged_at) where published_at is null;
+`.trim();
+export const SQL_OUTBOX_STAGE = `
+insert into x_outbox
+  (id, job, queue, input, idempotency_key, max_attempts, run_at, staged_at, tenant_id)
+values ($1, $2, $3, $4::jsonb, $5, $6, to_timestamp($7 / 1000.0), to_timestamp($8 / 1000.0), $9)
+`.trim();
+export const SQL_OUTBOX_CLAIM = `
+select id, job, queue, input, idempotency_key, max_attempts,
+       (extract(epoch from run_at) * 1000)::bigint    as run_at,
+       (extract(epoch from staged_at) * 1000)::bigint as staged_at,
+       tenant_id
+  from x_outbox
+ where published_at is null
+ order by staged_at
+ limit $1
+   for update skip locked
+`.trim();
+export const SQL_OUTBOX_MARK_PUBLISHED = `
+update x_outbox set published_at = to_timestamp($2 / 1000.0) where id = $1
+`.trim();
+//# sourceMappingURL=outbox.js.map

package/src/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["outbox.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,8FAA8F;AAC9F,sFAAsF;AACtF,qCAAqC;AACrC,EAAE;AACF,2EAA2E;AAC3E,sFAAsF;AACtF,EAAE;AACF,2FAA2F;AAC3F,6FAA6F;AAC7F,8FAA8F;AAG9F,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AA6B3C;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,MAAM,GAAG,IAAI,OAAO,EAA0B,CAAC;IACrD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAElD,MAAM,GAAG,GAAG,CAAC,EAAM,EAAU,EAAE,CAAC,EAAuB,CAAC;IAExD,OAAO;QACL,KAAK,CAAC,EAAE,EAAE,MAAM;YACd,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACzC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,CAAC,EAAE;YACP,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACzC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YACvB,KAAK,MAAM,MAAM,IAAI,MAAM;gBAAE,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC9D,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,QAAQ,CAAC,EAAE;YACT,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YACvB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,KAAK;YACT,MAAM,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC;iBAClC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC;iBACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;iBACvC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,aAAa,CAAC,EAAE,EAAE,EAAE;YAClB,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjC,IAAI,MAAM,KAAK,SAAS;gBAAE,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;YAC5E,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,YAAY;YACV,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;gBACxC,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS;oBAAE,KAAK,IAAI,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAmBD,yFAAyF;AACzF,MAAM,UAAU,WAAW,CACzB,IAAgB,EAChB,EAAM,EACN,MAAoB,EACpB,KAAQ,EACR,OAAO,GAAmB,EAAE;IAE5B,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAiB;QAC3B,EAAE,EAAE,IAAI,EAAE;QACV,GAAG,EAAE,MAAM,CAAC,IAAI;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,aAAa;QACrD,KAAK;QACL,cAAc,EAAE,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC;QAC/C,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;QAC1B,QAAQ,EAAE,EAAE;QACZ,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC;IACF,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAUD,MAAM,aAAa,GAAkB,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAE3E,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,SAA+B;IAChF,OAAO;QACL,KAAK,CAAC,OAAO,CACX,MAAoB,EACpB,KAAQ,EACR,OAAO,GAAmB,EAAE;YAE5B,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;YAE9D,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;gBACrB,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;oBACzD,MAAM,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;gBAClD,CAAC;gBACD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;oBACpC,KAAK;oBACL,cAAc,EAAE,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC;oBAC/C,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;oBAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;oBACzC,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;iBAC1E,CAAC,CAAC;YACL,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YACnE,kEAAkE;YAClE,OAAO,EAAE,GAAG,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC;AAeD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;IAC7C,IAAI,KAAiD,CAAC;IACtD,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,IAAI,GAAG,KAAK,IAAqB,EAAE;QACvC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;oBAC3B,IAAI,EAAE,MAAM,CAAC,GAAG;oBAChB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,cAAc,EAAE,MAAM,CAAC,cAAc;oBACrC,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;iBACxE,CAAC,CAAC;gBACH,MAAM,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;gBACnE,SAAS,IAAI,CAAC,CAAC;YACjB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,qFAAqF;gBACrF,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE;oBACxC,GAAG,EAAE,MAAM,CAAC,GAAG;oBACf,EAAE,EAAE,MAAM,CAAC,EAAE;oBACb,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO;QACL,IAAI;QACJ,KAAK;YACH,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAChC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;gBACvB,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;oBACvB,OAAO,GAAG,KAAK,CAAC;gBAClB,CAAC,CAAC,CAAC;YACL,CAAC,EAAE,UAAU,CAAC,CAAC;QACjB,CAAC;QACD,IAAI;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,aAAa,CAAC,KAAK,CAAC,CAAC;YAC9C,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;CAe/B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;CAI/B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;CAU/B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,MAAM,yBAAyB,GAAG;;CAExC,CAAC,IAAI,EAAE,CAAC"}