@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/esm/jobs/retention-schemas.js

@@ -0,0 +1,229 @@
+// =============================================================================
+// Jobs: the `retention` system-settings namespace's schemas (issue #898)
+// =============================================================================
+//
+// One `{ enabled, days }` policy per platform table that grows with every user
+// action and had no retention at all: the in-app inbox (`notifications`), the
+// delivery log (`notification_deliveries`), the admin audit trail
+// (`audit_events`) and background AI runs (`ai_runs`, whose `request` column
+// holds the user's full prompt, a privacy concern as much as a size one).
+//
+// The namespace declaration (`RETENTION_SYSTEM_SETTINGS`) and the nightly,
+// enqueue-only scheduler are the jobs slice's (`@marinoscar/platform-api/jobs`);
+// each purge handler is its table owner's. These are the schemas the
+// declaration is built from, moved verbatim from the reference app's
+// `common/schemas/` files, which re-export them. Every bound is unchanged, so
+// the OpenAPI document of `/api/system-settings` is too.
+//
+// The stored, the wire and the response shapes RESTATE each other on purpose,
+// as the `jobs` namespace's do (see `settings-schemas.ts`). NO `.default()`
+// anywhere: the defaults live in the declaration, never in a parse.
+// =============================================================================
+import { z } from 'zod';
+/**
+ * Upper bound on any `retention.*.days`: ten years, as for every retention
+ * field.
+ *
+ * @stability stable
+ */
+export const RETENTION_MAX_DAYS = 3650;
+/**
+ * Lower bound on any `retention.*.days`: one day.
+ *
+ * @stability experimental
+ */
+export const RETENTION_MIN_DAYS = 1;
+/**
+ * The platform's own `retention` keys, one per governed table, in the order
+ * the stored JSON, the composed schemas and the scheduler's enqueues use. An
+ * app adds policies of its own with `registerRetentionPolicy`
+ * (`@marinoscar/platform-api/jobs`); they follow these four.
+ *
+ * @stability stable
+ */
+export const BUILTIN_RETENTION_POLICY_KEYS = ['notifications', 'notificationDeliveries', 'auditEvents', 'aiRuns'];
+/**
+ * The platform's four `retention` keys, under their original name.
+ *
+ * @deprecated Use {@link BUILTIN_RETENTION_POLICY_KEYS}; the namespace is open and an app's registered policies are not listed here.
+ * @stability stable
+ */
+export const RETENTION_POLICY_KEYS = BUILTIN_RETENTION_POLICY_KEYS;
+/**
+ * What a retention policy key must look like: lower-case letter first, then
+ * letters and digits, 2 to 48 characters (the shape of a settings namespace
+ * field, so it is also a safe JSON key and a safe log token).
+ *
+ * @stability experimental
+ */
+export const RETENTION_POLICY_KEY_PATTERN = /^[a-z][A-Za-z0-9]{1,47}$/;
+/**
+ * A retention policy key: a built-in or an app's registered one.
+ *
+ * @stability experimental
+ */
+export const retentionPolicyKeySchema = z
+    .string()
+    .regex(RETENTION_POLICY_KEY_PATTERN, 'A retention policy key is 2 to 48 letters and digits, starting with a lower-case letter');
+/**
+ * One table's retention policy, as stored: whether the purge runs and how many
+ * days of rows it keeps.
+ *
+ * @stability stable
+ */
+export const retentionPolicySchema = z.object({
+    /** Whether the purge runs for this table. */
+    enabled: z.boolean(),
+    /** Days of rows kept; older rows are purged. */
+    days: z.number().int().min(1).max(RETENTION_MAX_DAYS),
+});
+/**
+ * The `retention` namespace, as stored.
+ *
+ * @stability stable
+ */
+export const systemRetentionSchema = z.object({
+    /** The in-app inbox (`notifications`). */
+    notifications: retentionPolicySchema,
+    /** The delivery log (`notification_deliveries`). */
+    notificationDeliveries: retentionPolicySchema,
+    /** The admin audit trail (`audit_events`); ships off. */
+    auditEvents: retentionPolicySchema,
+    /** Background AI runs (`ai_runs`). */
+    aiRuns: retentionPolicySchema,
+});
+const retentionPolicyPatchSchema = z.object({
+    /** Whether the purge runs for this table. */
+    enabled: z.boolean().optional(),
+    /** Days of rows kept. */
+    days: z.number().int().min(1).max(RETENTION_MAX_DAYS).optional(),
+});
+/**
+ * `retention`, one level deep and field by field, as stored:
+ * `{ "retention": { "auditEvents": { "enabled": true } } }` changes that one
+ * leaf.
+ *
+ * @stability stable
+ */
+export const systemRetentionPatchSchema = z.object({
+    /** The in-app inbox (`notifications`). */
+    notifications: retentionPolicyPatchSchema.optional(),
+    /** The delivery log (`notification_deliveries`). */
+    notificationDeliveries: retentionPolicyPatchSchema.optional(),
+    /** The admin audit trail (`audit_events`); ships off. */
+    auditEvents: retentionPolicyPatchSchema.optional(),
+    /** Background AI runs (`ai_runs`). */
+    aiRuns: retentionPolicyPatchSchema.optional(),
+});
+/**
+ * The `retention` branch of the PUT body.
+ *
+ * @stability stable
+ */
+export const retentionSettingsSchema = z.object({
+    /** The in-app inbox (`notifications`). */
+    notifications: retentionPolicySchema,
+    /** The delivery log (`notification_deliveries`). */
+    notificationDeliveries: retentionPolicySchema,
+    /** The admin audit trail (`audit_events`); ships off. */
+    auditEvents: retentionPolicySchema,
+    /** Background AI runs (`ai_runs`). */
+    aiRuns: retentionPolicySchema,
+});
+/**
+ * The `retention` branch of the PATCH body: optional at the namespace level
+ * and leaf by leaf inside.
+ *
+ * @stability stable
+ */
+export const retentionSettingsPatchSchema = z.object({
+    /** The in-app inbox (`notifications`). */
+    notifications: retentionPolicyPatchSchema.optional(),
+    /** The delivery log (`notification_deliveries`). */
+    notificationDeliveries: retentionPolicyPatchSchema.optional(),
+    /** The admin audit trail (`audit_events`); ships off. */
+    auditEvents: retentionPolicyPatchSchema.optional(),
+    /** Background AI runs (`ai_runs`). */
+    aiRuns: retentionPolicyPatchSchema.optional(),
+});
+/**
+ * The `retention` branch of the GET response: the OpenAPI-visible contract
+ * only, so `days` carries no bounds.
+ *
+ * @stability stable
+ */
+export const retentionResponseSchema = z.object({
+    /** The in-app inbox (`notifications`). */
+    notifications: z.object({
+        /** Whether the purge runs. */
+        enabled: z.boolean(),
+        /** Days of rows kept. */
+        days: z.number().int(),
+    }),
+    /** The delivery log (`notification_deliveries`). */
+    notificationDeliveries: z.object({
+        /** Whether the purge runs. */
+        enabled: z.boolean(),
+        /** Days of rows kept. */
+        days: z.number().int(),
+    }),
+    /** The admin audit trail (`audit_events`); ships off. */
+    auditEvents: z.object({
+        /** Whether the purge runs. */
+        enabled: z.boolean(),
+        /** Days of rows kept. */
+        days: z.number().int(),
+    }),
+    /** Background AI runs (`ai_runs`). */
+    aiRuns: z.object({
+        /** Whether the purge runs. */
+        enabled: z.boolean(),
+        /** Days of rows kept. */
+        days: z.number().int(),
+    }),
+});
+/**
+ * Composes the `retention` namespace's five schemas from a list of policies,
+ * in list order. Called with the four built-ins it yields schemas equal to
+ * {@link systemRetentionSchema} and its siblings (a contract test pins the
+ * JSON Schema), so the OpenAPI document is unchanged until an app registers a
+ * policy. No `.default()`: the defaults live in the declaration.
+ *
+ * Unknown keys in a body are stripped, never stored: a policy that is not
+ * registered cannot be written.
+ *
+ * @param policies - the policies, in the order the stored JSON uses.
+ * @returns the five branches.
+ * @throws Error when a key repeats or is not a valid policy key, or when a policy's bounds are not whole days with min at least 1, max at most {@link RETENTION_MAX_DAYS} and min not above max.
+ *
+ * @stability experimental
+ */
+export function buildRetentionSchemas(policies) {
+    const stored = {};
+    const patch = {};
+    const response = {};
+    for (const policy of policies) {
+        const min = policy.minDays ?? RETENTION_MIN_DAYS;
+        const max = policy.maxDays ?? RETENTION_MAX_DAYS;
+        if (!RETENTION_POLICY_KEY_PATTERN.test(policy.key)) {
+            throw new Error(`"${policy.key}" is not a valid retention policy key.`);
+        }
+        if (policy.key in stored)
+            throw new Error(`Retention policy "${policy.key}" appears twice.`);
+        if (!Number.isInteger(min) || !Number.isInteger(max) || min < RETENTION_MIN_DAYS || max > RETENTION_MAX_DAYS || min > max) {
+            throw new Error(`Retention policy "${policy.key}" needs whole-day bounds with ${RETENTION_MIN_DAYS} <= minDays <= maxDays <= ${RETENTION_MAX_DAYS}.`);
+        }
+        const days = z.number().int().min(min).max(max);
+        stored[policy.key] = z.object({ enabled: z.boolean(), days });
+        patch[policy.key] = z.object({ enabled: z.boolean().optional(), days: days.optional() }).optional();
+        response[policy.key] = z.object({ enabled: z.boolean(), days: z.number().int() });
+    }
+    return {
+        stored: z.object(stored),
+        patch: z.object(patch),
+        put: z.object(stored),
+        wirePatch: z.object(patch),
+        response: z.object(response),
+    };
+}
+//# sourceMappingURL=retention-schemas.js.map

package/dist/esm/jobs/retention-schemas.js.map

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

package/dist/esm/jobs/schemas.d.ts

@@ -0,0 +1,361 @@
+import { z } from 'zod';
+import { JOB_ETA_BASES, BUILTIN_JOB_REASONS, JOB_STATUSES, PROCESSED_WITHIN_VALUES } from './constants.js';
+/**
+ * The entries of the job status enum.
+ *
+ * @stability experimental
+ */
+export type JobStatusEnum = {
+    [K in (typeof JOB_STATUSES)[number]]: K;
+};
+/**
+ * The entries of the built-in job reason list.
+ *
+ * @stability experimental
+ */
+export type JobReasonEnum = {
+    [K in (typeof BUILTIN_JOB_REASONS)[number]]: K;
+};
+/**
+ * A job reason id: a string of the shape {@link JOB_REASON_PATTERN}, not an
+ * enum, so an app's `registerJobReason` ids pass. Whether an id is registered
+ * is checked where a job is enqueued, never in this schema.
+ *
+ * @stability experimental
+ */
+export declare const jobReasonSchema: z.ZodString;
+/**
+ * The entries of the processed-within window enum.
+ *
+ * @stability experimental
+ */
+export type ProcessedWithinEnum = {
+    [K in (typeof PROCESSED_WITHIN_VALUES)[number]]: K;
+};
+/**
+ * The entries of the ETA basis enum.
+ *
+ * @stability experimental
+ */
+export type JobEtaBasisEnum = {
+    [K in (typeof JOB_ETA_BASES)[number]]: K;
+};
+/**
+ * The entries of a boolean query flag (`'true'` / `'false'`).
+ *
+ * @stability experimental
+ */
+export type JobBooleanFlagEnum = {
+    [K in 'true' | 'false']: K;
+};
+/**
+ * One `jobs` row as `GET /api/admin/jobs` lists it (no payload, no claim token).
+ *
+ * @stability experimental
+ */
+export declare const jobSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    type: z.ZodString;
+    typeLabel: z.ZodString;
+    subjectType: z.ZodNullable<z.ZodString>;
+    subjectId: z.ZodNullable<z.ZodString>;
+    dedupKey: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<JobStatusEnum>;
+    reason: z.ZodString;
+    reasonLabel: z.ZodString;
+    priority: z.ZodNumber;
+    providerKey: z.ZodNullable<z.ZodString>;
+    modelVersion: z.ZodNullable<z.ZodString>;
+    attempts: z.ZodNumber;
+    lastError: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    startedAt: z.ZodNullable<z.ZodISODateTime>;
+    finishedAt: z.ZodNullable<z.ZodISODateTime>;
+    scheduledFor: z.ZodNullable<z.ZodISODateTime>;
+    rateLimitedAt: z.ZodNullable<z.ZodISODateTime>;
+    rateLimitHits: z.ZodNumber;
+    claimedByNodeId: z.ZodNullable<z.ZodUUID>;
+    leaseExpiresAt: z.ZodNullable<z.ZodISODateTime>;
+    executor: z.ZodNullable<z.ZodString>;
+    orgId: z.ZodNullable<z.ZodUUID>;
+}, z.core.$strip>;
+/**
+ * The query of `GET /api/admin/jobs`: filters, the activity window and pagination.
+ *
+ * @stability experimental
+ */
+export declare const jobListQuerySchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    status: z.ZodOptional<z.ZodEnum<JobStatusEnum>>;
+    type: z.ZodOptional<z.ZodString>;
+    subjectType: z.ZodOptional<z.ZodString>;
+    subjectId: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodUUID>;
+    scheduled: z.ZodOptional<z.ZodPipe<z.ZodEnum<JobBooleanFlagEnum>, z.ZodTransform<boolean, "true" | "false">>>;
+    processedWithin: z.ZodDefault<z.ZodEnum<ProcessedWithinEnum>>;
+}, z.core.$strip>;
+/**
+ * The parsed, defaulted shape `JobAdminService.list` consumes.
+ *
+ * @stability experimental
+ */
+export type JobListQuery = z.output<typeof jobListQuerySchema>;
+/**
+ * Counts per status, zero-filled — every key is always present.
+ *
+ * @stability experimental
+ */
+export declare const jobStatusCountsSchema: z.ZodObject<{
+    pending: z.ZodNumber;
+    running: z.ZodNumber;
+    succeeded: z.ZodNumber;
+    failed: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Counts per status, every key present.
+ *
+ * @stability experimental
+ */
+export type JobStatusCounts = z.output<typeof jobStatusCountsSchema>;
+/**
+ * One row of the by-type breakdown.
+ *
+ * Ordered by `total` descending then `type` ascending in the service, so the
+ * busiest type is first and the order is stable between two polls that see the
+ * same counts — a table whose rows reshuffle every two seconds is unreadable.
+ *
+ * @stability experimental
+ */
+export declare const jobTypeStatsSchema: z.ZodObject<{
+    type: z.ZodString;
+    label: z.ZodString;
+    total: z.ZodNumber;
+    byStatus: z.ZodObject<{
+        pending: z.ZodNumber;
+        running: z.ZodNumber;
+        succeeded: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * The body of `GET /api/admin/jobs/stats`: the queue's summary.
+ *
+ * @stability experimental
+ */
+export declare const jobStatsSchema: z.ZodObject<{
+    total: z.ZodNumber;
+    byStatus: z.ZodObject<{
+        pending: z.ZodNumber;
+        running: z.ZodNumber;
+        succeeded: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, z.core.$strip>;
+    byType: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodString;
+        total: z.ZodNumber;
+        byStatus: z.ZodObject<{
+            pending: z.ZodNumber;
+            running: z.ZodNumber;
+            succeeded: z.ZodNumber;
+            failed: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    scheduled: z.ZodNumber;
+    stuckRunning: z.ZodNumber;
+    stuckThresholdMinutes: z.ZodNumber;
+    generatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * The query of `GET /api/admin/jobs/insights`: the history window in days.
+ *
+ * @stability experimental
+ */
+export declare const jobInsightsQuerySchema: z.ZodObject<{
+    windowDays: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * The parsed, defaulted shape `JobInsightsService.insights` consumes.
+ *
+ * @stability experimental
+ */
+export type JobInsightsQuery = z.output<typeof jobInsightsQuerySchema>;
+/**
+ * Durations over one set of succeeded jobs. See the header on the nulls.
+ *
+ * @stability experimental
+ */
+export declare const jobDurationStatsSchema: z.ZodObject<{
+    samples: z.ZodNumber;
+    avgMs: z.ZodNullable<z.ZodNumber>;
+    p50Ms: z.ZodNullable<z.ZodNumber>;
+    p95Ms: z.ZodNullable<z.ZodNumber>;
+    throughputPerMin: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Duration percentiles of one population of succeeded jobs.
+ *
+ * @stability experimental
+ */
+export type JobDurationStats = z.output<typeof jobDurationStatsSchema>;
+/**
+ * Duration percentiles of one job type over the window.
+ *
+ * @stability experimental
+ */
+export declare const jobTypeDurationStatsSchema: z.ZodObject<{
+    samples: z.ZodNumber;
+    avgMs: z.ZodNullable<z.ZodNumber>;
+    p50Ms: z.ZodNullable<z.ZodNumber>;
+    p95Ms: z.ZodNullable<z.ZodNumber>;
+    throughputPerMin: z.ZodNumber;
+    type: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+/**
+ * One job type's drain estimate.
+ *
+ * @stability experimental
+ */
+export declare const jobEtaSchema: z.ZodObject<{
+    type: z.ZodString;
+    label: z.ZodString;
+    pending: z.ZodNumber;
+    running: z.ZodNumber;
+    remaining: z.ZodNumber;
+    avgMs: z.ZodNumber;
+    basis: z.ZodEnum<JobEtaBasisEnum>;
+    estimatedMs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * One job type's all-time totals (rollup plus live rows).
+ *
+ * @stability experimental
+ */
+export declare const jobLifetimeStatsSchema: z.ZodObject<{
+    type: z.ZodString;
+    label: z.ZodString;
+    succeeded: z.ZodNumber;
+    failed: z.ZodNumber;
+    total: z.ZodNumber;
+    avgMs: z.ZodNullable<z.ZodNumber>;
+    durationSamples: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * The body of `GET /api/admin/jobs/insights`: live counts, windowed history, lifetime totals and ETAs.
+ *
+ * @stability experimental
+ */
+export declare const jobInsightsSchema: z.ZodObject<{
+    windowDays: z.ZodNumber;
+    generatedAt: z.ZodISODateTime;
+    concurrency: z.ZodNumber;
+    live: z.ZodObject<{
+        total: z.ZodNumber;
+        byStatus: z.ZodObject<{
+            pending: z.ZodNumber;
+            running: z.ZodNumber;
+            succeeded: z.ZodNumber;
+            failed: z.ZodNumber;
+        }, z.core.$strip>;
+        byType: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            label: z.ZodString;
+            total: z.ZodNumber;
+            byStatus: z.ZodObject<{
+                pending: z.ZodNumber;
+                running: z.ZodNumber;
+                succeeded: z.ZodNumber;
+                failed: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        scheduled: z.ZodNumber;
+        rateLimited: z.ZodNumber;
+        retried: z.ZodNumber;
+    }, z.core.$strip>;
+    history: z.ZodObject<{
+        windowStart: z.ZodISODateTime;
+        throughputSince: z.ZodISODateTime;
+        overall: z.ZodObject<{
+            samples: z.ZodNumber;
+            avgMs: z.ZodNullable<z.ZodNumber>;
+            p50Ms: z.ZodNullable<z.ZodNumber>;
+            p95Ms: z.ZodNullable<z.ZodNumber>;
+            throughputPerMin: z.ZodNumber;
+        }, z.core.$strip>;
+        byType: z.ZodArray<z.ZodObject<{
+            samples: z.ZodNumber;
+            avgMs: z.ZodNullable<z.ZodNumber>;
+            p50Ms: z.ZodNullable<z.ZodNumber>;
+            p95Ms: z.ZodNullable<z.ZodNumber>;
+            throughputPerMin: z.ZodNumber;
+            type: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    eta: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodString;
+        pending: z.ZodNumber;
+        running: z.ZodNumber;
+        remaining: z.ZodNumber;
+        avgMs: z.ZodNumber;
+        basis: z.ZodEnum<JobEtaBasisEnum>;
+        estimatedMs: z.ZodNumber;
+    }, z.core.$strip>>;
+    lifetime: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodString;
+        succeeded: z.ZodNumber;
+        failed: z.ZodNumber;
+        total: z.ZodNumber;
+        avgMs: z.ZodNullable<z.ZodNumber>;
+        durationSamples: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The result of resetting the job history.
+ *
+ * @stability experimental
+ */
+export declare const resetHistoryResultSchema: z.ZodObject<{
+    reset: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * The body of `POST /api/admin/jobs/retry-failed`.
+ *
+ * @stability experimental
+ */
+export declare const retryFailedSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The body of `POST /api/admin/jobs/reset-stuck`.
+ *
+ * @stability experimental
+ */
+export declare const resetStuckSchema: z.ZodObject<{
+    olderThanMinutes: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * The result of `POST /api/admin/jobs/retry-failed`.
+ *
+ * @stability experimental
+ */
+export declare const retryFailedResultSchema: z.ZodObject<{
+    retried: z.ZodNumber;
+    skipped: z.ZodNumber;
+    remaining: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * The result of `POST /api/admin/jobs/reset-stuck`.
+ *
+ * @stability experimental
+ */
+export declare const resetStuckResultSchema: z.ZodObject<{
+    reset: z.ZodNumber;
+    failed: z.ZodNumber;
+    thresholdMinutes: z.ZodNumber;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/esm/jobs/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/jobs/schemas.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,aAAa,EACb,mBAAmB,EAEnB,YAAY,EAEZ,uBAAuB,EACxB,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;KAAG,CAAC,IAAI,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;CAAE,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;KAAG,CAAC,IAAI,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;CAAE,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,aAE+F,CAAC;AAE5H;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;KAAG,CAAC,IAAI,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;CAAE,CAAC;AAEzF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;KAAG,CAAC,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;CAAE,CAAC;AAE3E;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;KAAG,CAAC,IAAI,MAAM,GAAG,OAAO,GAAG,CAAC;CAAE,CAAC;AA8ChE;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;iBAkEpB,CAAC;AA8DH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAoC7B,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AA4C/D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;iBAShC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAS7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;iBA6BzB,CAAC;AA+EH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;iBAcjC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMvE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;iBAwBjC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;iBAKrC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;iBAqBvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;iBAqBjC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqE5B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;iBASnC,CAAC;AA4CH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;iBAS5B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;iBAS3B,CAAC;AAMH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;iBAqBlC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;iBAOjC,CAAC"}