@azurioh/discord-kernel 0.1.0 → 1.0.0

package/dist/settings/testing/settings-store-contract.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSettingsStoreContract = runSettingsStoreContract;
+const business_error_1 = require("../../errors/business-error");
+const GUILD_A = "100000000000000001";
+const GUILD_B = "100000000000000002";
+const MODULE_A = "tickets";
+const MODULE_B = "welcome";
+function record(overrides = {}) {
+    return {
+        guildId: GUILD_A,
+        moduleId: MODULE_A,
+        version: 1,
+        revision: 1,
+        values: { maxOpen: 2 },
+        updatedAt: "2026-01-01T00:00:00.000Z",
+        updatedBy: "200000000000000001",
+        ...overrides,
+    };
+}
+async function captureError(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        return error;
+    }
+    return undefined;
+}
+/** The caller's view of a record it may scribble on, to prove the store kept its own copy. */
+function mutableValues(stored) {
+    return (stored?.values ?? {});
+}
+/**
+ * Behaviour every {@link SettingsStore} implementation must have: one case per
+ * guarantee stated on the port. Run it from the adapter's own test file with
+ * the test runner's `describe`, `it` and `expect`:
+ * `runSettingsStoreContract(createMyStore, { describe, it, expect })`.
+ *
+ * @param createStore - returns a store with no record in it; called once per case.
+ * @param runner - the test runner's functions, so this suite imports no framework.
+ */
+function runSettingsStoreContract(createStore, runner) {
+    const { describe, it, expect } = runner;
+    /**
+     * Deleting the default record must leave `other` — the same record moved to
+     * another guild or another module — exactly as it was written.
+     */
+    async function expectDeleteLeavesAlone(other) {
+        const store = await createStore();
+        await store.write(record(), { expectedRevision: null });
+        await store.write(other, { expectedRevision: null });
+        await store.delete(GUILD_A, MODULE_A);
+        expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+        expect(await store.read(other.guildId, other.moduleId)).toEqual(other);
+    }
+    describe("SettingsStore contract", () => {
+        it("reads null when no record exists", async () => {
+            const store = await createStore();
+            expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+        });
+        it("creates a record when the expected revision is null", async () => {
+            const store = await createStore();
+            const created = record();
+            await store.write(created, { expectedRevision: null });
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(created);
+        });
+        it("rejects a create when a record already exists", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            const error = await captureError(() => store.write(record({ values: { maxOpen: 3 } }), { expectedRevision: null }));
+            expect(error).toBeInstanceOf(business_error_1.ConflictError);
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+        });
+        it("rejects an update when no record exists", async () => {
+            const store = await createStore();
+            const error = await captureError(() => store.write(record({ revision: 2 }), { expectedRevision: 1 }));
+            expect(error).toBeInstanceOf(business_error_1.ConflictError);
+            expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+        });
+        it("rejects a write with a stale revision and keeps the stored record", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            const second = record({ revision: 2, values: { maxOpen: 3 } });
+            await store.write(second, { expectedRevision: 1 });
+            const error = await captureError(() => store.write(record({ revision: 2, values: { maxOpen: 4 } }), { expectedRevision: 1 }));
+            expect(error).toBeInstanceOf(business_error_1.ConflictError);
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(second);
+        });
+        it("increments the revision by one on each write", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            await store.write(record({ revision: 2 }), { expectedRevision: 1 });
+            await store.write(record({ revision: 3 }), { expectedRevision: 2 });
+            const stored = await store.read(GUILD_A, MODULE_A);
+            expect(stored?.revision).toBe(3);
+        });
+        it("deletes a record", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            await store.delete(GUILD_A, MODULE_A);
+            expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+        });
+        it("deletes a missing record without error", async () => {
+            const store = await createStore();
+            const error = await captureError(() => store.delete(GUILD_A, MODULE_A));
+            expect(error).toBe(undefined);
+            expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+        });
+        it("accepts a create again after a delete", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            await store.delete(GUILD_A, MODULE_A);
+            await store.write(record(), { expectedRevision: null });
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+        });
+        it("keeps guilds isolated", async () => {
+            await expectDeleteLeavesAlone(record({ guildId: GUILD_B, values: { maxOpen: 5 } }));
+        });
+        it("keeps modules isolated", async () => {
+            await expectDeleteLeavesAlone(record({ moduleId: MODULE_B, values: { greeting: "hi" } }));
+        });
+        it("round-trips every JSON value shape", async () => {
+            const store = await createStore();
+            const created = record({
+                values: {
+                    text: "Salut « à vous » 👋",
+                    count: -1.5,
+                    enabled: false,
+                    cleared: null,
+                    roles: ["300000000000000001", "300000000000000002"],
+                    nested: { toggles: { a: true }, list: [] },
+                },
+            });
+            await store.write(created, { expectedRevision: null });
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(created);
+        });
+        it("keeps an absent updatedBy absent", async () => {
+            const store = await createStore();
+            const { updatedBy: _omitted, ...anonymous } = record();
+            await store.write(anonymous, { expectedRevision: null });
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(anonymous);
+        });
+        it("keeps a written record independent of the caller's object", async () => {
+            const store = await createStore();
+            const written = record();
+            await store.write(written, { expectedRevision: null });
+            mutableValues(written).maxOpen = 99;
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+        });
+        it("returns a record the caller can change without changing the store", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            mutableValues(await store.read(GUILD_A, MODULE_A)).maxOpen = 99;
+            expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+        });
+        it("lets exactly one of two concurrent creates win", async () => {
+            const store = await createStore();
+            const first = record({ values: { maxOpen: 3 } });
+            const second = record({ values: { maxOpen: 4 } });
+            const outcomes = await Promise.allSettled([
+                store.write(first, { expectedRevision: null }),
+                store.write(second, { expectedRevision: null }),
+            ]);
+            await expectOneWinner(store, outcomes, [first, second]);
+        });
+        it("lets exactly one of two concurrent updates of the same revision win", async () => {
+            const store = await createStore();
+            await store.write(record(), { expectedRevision: null });
+            const first = record({ revision: 2, values: { maxOpen: 3 } });
+            const second = record({ revision: 2, values: { maxOpen: 4 } });
+            const outcomes = await Promise.allSettled([
+                store.write(first, { expectedRevision: 1 }),
+                store.write(second, { expectedRevision: 1 }),
+            ]);
+            await expectOneWinner(store, outcomes, [first, second]);
+        });
+    });
+    /**
+     * Of two racing writes, exactly one lands, the other fails with a
+     * `ConflictError`, and the stored record is the winner's.
+     */
+    async function expectOneWinner(store, outcomes, written) {
+        const winners = outcomes.flatMap((outcome, index) => outcome.status === "fulfilled" ? [written[index]] : []);
+        const losers = outcomes.flatMap((outcome) => outcome.status === "rejected" ? [outcome.reason] : []);
+        expect(winners.length).toBe(1);
+        expect(losers.length).toBe(1);
+        expect(losers[0]).toBeInstanceOf(business_error_1.ConflictError);
+        expect(await store.read(GUILD_A, MODULE_A)).toEqual(winners[0]);
+    }
+}
+//# sourceMappingURL=settings-store-contract.js.map

package/dist/settings/testing/settings-store-contract.js.map

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

package/dist/settings/timed-search.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "../logger";
+/**
+ * How long a suggestion search may run (FR-024): past it the search is
+ * abandoned, so an autocomplete still answers within Discord's 3 s window.
+ */
+export declare const SUGGESTION_TIMEOUT_MS = 2500;
+/**
+ * Run a suggestion search within {@link SUGGESTION_TIMEOUT_MS}. A search that
+ * runs longer or fails yields `fallback` and a `warn` log naming `at`; it never
+ * throws. The timer is cleared as soon as the race settles, so no timer
+ * outlives the call. It runs on the global timers, which a test drives with
+ * fake timers.
+ *
+ * @param params.search - the search; may throw or reject.
+ * @param params.fallback - what a slow or failed search yields.
+ * @param params.logger - where a slow or failed search is reported.
+ * @param params.at - what the log names: module, field, guild.
+ * @returns the search's result, or `fallback`.
+ */
+export declare function timedSearch<T>(params: {
+    search: () => Promise<T>;
+    fallback: T;
+    logger: Logger;
+    at: Readonly<Record<string, unknown>>;
+}): Promise<T>;
+//# sourceMappingURL=timed-search.d.ts.map

package/dist/settings/timed-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timed-search.d.ts","sourceRoot":"","sources":["../../src/settings/timed-search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAK3C;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5C,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,QAAQ,EAAE,CAAC,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtC,GAAG,OAAO,CAAC,CAAC,CAAC,CAyBb"}

package/dist/settings/timed-search.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUGGESTION_TIMEOUT_MS = void 0;
+exports.timedSearch = timedSearch;
+const error_message_1 = require("../errors/error-message");
+/**
+ * How long a suggestion search may run (FR-024): past it the search is
+ * abandoned, so an autocomplete still answers within Discord's 3 s window.
+ */
+exports.SUGGESTION_TIMEOUT_MS = 2_500;
+/** Marks the timer winning the race, whatever the search resolves to. */
+const TIMED_OUT = Symbol("timed out");
+/**
+ * Run a suggestion search within {@link SUGGESTION_TIMEOUT_MS}. A search that
+ * runs longer or fails yields `fallback` and a `warn` log naming `at`; it never
+ * throws. The timer is cleared as soon as the race settles, so no timer
+ * outlives the call. It runs on the global timers, which a test drives with
+ * fake timers.
+ *
+ * @param params.search - the search; may throw or reject.
+ * @param params.fallback - what a slow or failed search yields.
+ * @param params.logger - where a slow or failed search is reported.
+ * @param params.at - what the log names: module, field, guild.
+ * @returns the search's result, or `fallback`.
+ */
+async function timedSearch(params) {
+    const { search, fallback, logger, at } = params;
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), exports.SUGGESTION_TIMEOUT_MS);
+    });
+    try {
+        const result = await Promise.race([(async () => search())(), timeout]);
+        if (result === TIMED_OUT) {
+            logger.warn({ ...at, timeoutMs: exports.SUGGESTION_TIMEOUT_MS }, "Settings suggestion search timed out; offering nothing");
+            return fallback;
+        }
+        return result;
+    }
+    catch (error) {
+        logger.warn({ ...at, err: (0, error_message_1.errorMessage)(error) }, "Settings suggestion search failed; offering nothing");
+        return fallback;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=timed-search.js.map

package/dist/settings/timed-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timed-search.js","sourceRoot":"","sources":["../../src/settings/timed-search.ts"],"names":[],"mappings":";;;AAyBA,kCA8BC;AAvDD,0DAAsD;AAGtD;;;GAGG;AACU,QAAA,qBAAqB,GAAG,KAAK,CAAC;AAE3C,yEAAyE;AACzE,MAAM,SAAS,GAAkB,MAAM,CAAC,WAAW,CAAC,CAAC;AAErD;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,WAAW,CAAI,MAKpC;IACA,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC;IAChD,IAAI,KAAgD,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,EAAE;QACzD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,6BAAqB,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QACvE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CACV,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,6BAAqB,EAAE,EAC3C,wDAAwD,CACxD,CAAC;YACF,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,CAAC,IAAI,CACV,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAA,4BAAY,EAAC,KAAK,CAAC,EAAE,EACnC,qDAAqD,CACrD,CAAC;QACF,OAAO,QAAQ,CAAC;IACjB,CAAC;YAAS,CAAC;QACV,YAAY,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACF,CAAC"}

package/dist/settings/types.d.ts

@@ -0,0 +1,37 @@
+import type { Field, FieldPresence } from "../settings/fields/field";
+/** The fields of a declaration, by key. */
+type FieldsOf<D> = D extends {
+    readonly fields: infer F;
+} ? F : never;
+/**
+ * The value type module logic reads for one field: `T` when the field has a
+ * default (a toggles field always has one), `T | undefined` otherwise, even
+ * when required: a guild may not have configured it yet.
+ */
+export type FieldValue<F> = F extends Field<infer T, "defined"> ? T : F extends Field<infer T, FieldPresence> ? T | undefined : never;
+/** What a surface shows for a secret: whether it is set, never its value. */
+export interface SecretState {
+    readonly isSet: boolean;
+}
+/** The value type a surface reads for one field: secrets become {@link SecretState}. */
+export type SurfaceFieldValue<F> = F extends {
+    readonly spec: {
+        readonly kind: "secret";
+    };
+} ? SecretState : FieldValue<F>;
+/**
+ * The values module logic reads from a declaration, typed from it: one entry
+ * per declared field, secrets included.
+ */
+export type SettingsValues<D> = {
+    readonly [K in keyof FieldsOf<D>]: FieldValue<FieldsOf<D>[K]>;
+};
+/**
+ * The values a configuration surface reads from a declaration: like
+ * {@link SettingsValues}, with each secret replaced by {@link SecretState}.
+ */
+export type SurfaceValues<D> = {
+    readonly [K in keyof FieldsOf<D>]: SurfaceFieldValue<FieldsOf<D>[K]>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/settings/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/settings/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAEpE,2CAA2C;AAC3C,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACvB,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,GAChC,CAAC,GACD,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,GACtC,CAAC,GAAG,SAAS,GACb,KAAK,CAAC;AAEX,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAA;CAAE,GACxF,WAAW,GACX,UAAU,CAAC,CAAC,CAAC,CAAC;AAEjB;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC/B,QAAQ,EAAE,CAAC,IAAI,MAAM,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC9B,QAAQ,EAAE,CAAC,IAAI,MAAM,QAAQ,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACpE,CAAC"}

package/dist/settings/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/settings/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/settings/types.ts"],"names":[],"mappings":""}

package/dist/settings/validate.d.ts

@@ -0,0 +1,55 @@
+import type { SettingsDeclaration } from "../settings/define-settings";
+import type { SettingsIssue } from "../settings/settings-validation-error";
+import { type SuggestionPorts } from "../settings/suggest";
+/**
+ * Outcome of {@link validateSettings}: the submitted fields in their stored
+ * form, or every issue found. A field submitted as `null` or `undefined` is
+ * unset: it appears in `values` with the value `undefined`.
+ */
+export type SettingsValidation = {
+    readonly ok: true;
+    readonly values: Readonly<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SettingsIssue[];
+};
+/**
+ * Who submits and what stage 2 reads: the guild's directory, the ports a
+ * strict field's search runs with, the requester, and the guild's current
+ * values, read only when a strict search needs them.
+ */
+export interface ValidationScope {
+    readonly ports: SuggestionPorts;
+    readonly guildId: string;
+    readonly userId: string;
+    readonly locale: string;
+    /** The guild's current values as a surface reads them (secrets as whether they are set). */
+    readonly currentValues: () => Promise<Readonly<Record<string, unknown>>>;
+}
+/**
+ * Validate a settings submission against its declaration, in two stages.
+ * Stage 1 checks each submitted field on its own (kind, bounds, lengths, list
+ * size, duplicates, enum membership, required fields being unset). Stage 2 runs
+ * only on the fields that passed stage 1: it asks the guild directory whether
+ * each referenced channel, role and member exists, and whether a channel is of
+ * an allowed type; and it asks a strict field's search whether it knows the
+ * value (FR-023): `label(value)` must name it, or, without `label`, a result
+ * of `resolve(String(value))` must hold exactly that value. A strict search
+ * that runs past its budget or fails knows nothing (logged): the value is
+ * refused as `unknownChoice` rather than stored unchecked. Keys the
+ * declaration lacks are rejected.
+ *
+ * @param params.declaration - the module's settings declaration.
+ * @param params.patch - the submitted fields, keyed by field key; any value.
+ * @param params.scope - the guild, the requester and the ports stage 2 reads.
+ * @returns the stored form of every submitted field, or every issue found, in
+ * submission order, with catalog keys from {@link SETTINGS_ISSUE_MESSAGES}.
+ * @throws ValidationError when the patch is not a plain object (a malformed
+ * request, not an invalid value).
+ */
+export declare function validateSettings(params: {
+    declaration: SettingsDeclaration;
+    patch: unknown;
+    scope: ValidationScope;
+}): Promise<SettingsValidation>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/settings/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/settings/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAOtE,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,sCAAsC,CAAC;AAC7F,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,CAAC;AAiBrE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC9C,WAAW,EAAE,mBAAmB,CAAC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,eAAe,CAAC;CACvB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6B9B"}

package/dist/settings/validate.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSettings = validateSettings;
+const business_error_1 = require("../errors/business-error");
+const field_search_1 = require("../settings/field-search");
+const field_1 = require("../settings/fields/field");
+const zod_schema_1 = require("../settings/fields/zod-schema");
+const is_plain_object_1 = require("../settings/is-plain-object");
+const messages_1 = require("../settings/messages");
+const suggest_1 = require("../settings/suggest");
+/**
+ * Validate a settings submission against its declaration, in two stages.
+ * Stage 1 checks each submitted field on its own (kind, bounds, lengths, list
+ * size, duplicates, enum membership, required fields being unset). Stage 2 runs
+ * only on the fields that passed stage 1: it asks the guild directory whether
+ * each referenced channel, role and member exists, and whether a channel is of
+ * an allowed type; and it asks a strict field's search whether it knows the
+ * value (FR-023): `label(value)` must name it, or, without `label`, a result
+ * of `resolve(String(value))` must hold exactly that value. A strict search
+ * that runs past its budget or fails knows nothing (logged): the value is
+ * refused as `unknownChoice` rather than stored unchecked. Keys the
+ * declaration lacks are rejected.
+ *
+ * @param params.declaration - the module's settings declaration.
+ * @param params.patch - the submitted fields, keyed by field key; any value.
+ * @param params.scope - the guild, the requester and the ports stage 2 reads.
+ * @returns the stored form of every submitted field, or every issue found, in
+ * submission order, with catalog keys from {@link SETTINGS_ISSUE_MESSAGES}.
+ * @throws ValidationError when the patch is not a plain object (a malformed
+ * request, not an invalid value).
+ */
+async function validateSettings(params) {
+    const { declaration, patch, scope } = params;
+    if (!(0, is_plain_object_1.isPlainObject)(patch)) {
+        throw new business_error_1.ValidationError(`Settings patch for module "${declaration.id}" must be an object keyed by field`);
+    }
+    const entries = Object.entries(patch);
+    const parsed = entries.map(([key, value]) => parseEntry({ declaration, key, value }));
+    // A secret stays out of what a search sees, as it stays out of every surface read.
+    const submitted = Object.fromEntries(parsed.flatMap((entry) => entry.ok && entry.declared.spec.kind !== "secret" ? [[entry.key, entry.value]] : []));
+    const values = lazyValues({ scope, submitted });
+    const outcomes = await Promise.all(parsed.map((entry) => entry.ok ? checkEntry({ scope, declaration, entry, values }) : entry.outcome));
+    const issues = outcomes.flatMap((entry) => entry.issues);
+    if (issues.length > 0) {
+        return { ok: false, issues };
+    }
+    return {
+        ok: true,
+        values: Object.fromEntries(entries.map(([key], index) => [key, outcomes[index]?.value])),
+    };
+}
+/**
+ * The values a strict search sees as "currently entered": the guild's current
+ * values with the submitted ones over them. Read once, and only when a strict
+ * search asks.
+ */
+function lazyValues(params) {
+    let values;
+    return () => {
+        values ??= params.scope
+            .currentValues()
+            .then((current) => ({ ...current, ...params.submitted }));
+        return values;
+    };
+}
+/** Stage 1: one submitted field checked on its own. */
+function parseEntry(params) {
+    const { declaration, key, value } = params;
+    const declared = Object.hasOwn(declaration.fields, key) ? declaration.fields[key] : undefined;
+    if (declared === undefined) {
+        return failed({ key, issues: [{ path: [], code: "unknownField", params: {} }] });
+    }
+    if (value === null || value === undefined) {
+        if (declared.required && declared.default === undefined) {
+            return failed({ key, issues: [{ path: [], code: "required", params: {} }] });
+        }
+        return { ok: true, key, declared, value: undefined };
+    }
+    const parsed = (0, zod_schema_1.parseFieldValue)({ field: declared, value });
+    if (!parsed.ok) {
+        return failed({ key, issues: parsed.issues });
+    }
+    return { ok: true, key, declared, value: parsed.value };
+}
+function failed(params) {
+    return { ok: false, outcome: outcome(params) };
+}
+/** Stage 2 on a field that passed stage 1; an unset field has nothing to check. */
+async function checkEntry(params) {
+    const { entry } = params;
+    if (entry.value === undefined) {
+        return { value: undefined, issues: [] };
+    }
+    const issues = await checkReferences({
+        ...params,
+        spec: entry.declared.spec,
+        value: entry.value,
+    });
+    return outcome({ key: entry.key, issues, value: entry.value });
+}
+function outcome(params) {
+    const { key, issues, value } = params;
+    return { value, issues: issues.map((issue) => toSettingsIssue(key, issue)) };
+}
+/** Stage 2 on a value, item by item for a list. */
+async function checkReferences(params) {
+    const { spec, value } = params;
+    if (spec.kind === "list" && Array.isArray(value)) {
+        const codes = await Promise.all(value.map((item) => checkValue({ ...params, spec: spec.item.spec, value: item })));
+        return codes.flatMap((code, index) => code === undefined ? [] : [{ path: [index], code, params: {} }]);
+    }
+    const code = await checkValue(params);
+    return code === undefined ? [] : [{ path: [], code, params: {} }];
+}
+/** The guild check, or the strict check, one value needs; `undefined` when it passes. */
+async function checkValue(params) {
+    const { scope, declaration, entry, values, spec, value } = params;
+    const search = (0, field_search_1.fieldSearch)(spec);
+    if (search?.strict === true) {
+        const label = await (0, suggest_1.dynamicLabel)({
+            scope: {
+                ...scope.ports,
+                moduleId: declaration.id,
+                key: entry.key,
+                ctx: {
+                    guildId: scope.guildId,
+                    userId: scope.userId,
+                    locale: scope.locale,
+                    values: withoutKey(await values(), entry.key),
+                },
+            },
+            suggest: search,
+            value,
+        });
+        return label === undefined ? "unknownChoice" : undefined;
+    }
+    return checkEntity({ guilds: scope.ports.guilds, guildId: scope.guildId, spec, value });
+}
+/** The other values: a search is told what else is entered, not its own field's value. */
+function withoutKey(values, key) {
+    const { [key]: _own, ...others } = values;
+    return others;
+}
+/**
+ * Whether the channel, role or member a value references is usable on the
+ * guild. Stage 1 makes such a value a snowflake string; any other value
+ * references no guild entity and needs no check.
+ */
+async function checkEntity(params) {
+    const { guilds, guildId, spec, value } = params;
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    switch (spec.kind) {
+        case "channel": {
+            const channel = await guilds.channel(guildId, value);
+            if (channel === null) {
+                return "notFound";
+            }
+            if (spec.types !== undefined && !spec.types.includes(channel.kind)) {
+                return "channelType";
+            }
+            return undefined;
+        }
+        case "role":
+            return (await guilds.role(guildId, value)) === null ? "notFound" : undefined;
+        case "user":
+            return (await guilds.member(guildId, value)) === null ? "notFound" : undefined;
+        case "color":
+        case "duration":
+        case "enum":
+        case "integer":
+        case "number":
+        case "text":
+        case "boolean":
+        case "secret":
+        case "list":
+        case "toggles":
+            return undefined;
+        default:
+            return (0, field_1.unhandledFieldKind)(spec);
+    }
+}
+/** `[i]` for a list index, `.name` for a toggle key. */
+function pathSuffix(segment) {
+    return typeof segment === "number" ? `[${segment}]` : `.${segment}`;
+}
+function toSettingsIssue(key, issue) {
+    const translationKey = messages_1.SETTINGS_ISSUE_MESSAGES[issue.code];
+    const field = `${key}${issue.path.map(pathSuffix).join("")}`;
+    const translation = Object.keys(issue.params).length === 0
+        ? { key: translationKey }
+        : { key: translationKey, params: issue.params };
+    return { field, code: issue.code, translation };
+}
+//# sourceMappingURL=validate.js.map

package/dist/settings/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/settings/validate.ts"],"names":[],"mappings":";;AAsEA,4CAiCC;AAvGD,4DAA0D;AAE1D,0DAAsD;AACtD,mDAA4F;AAC5F,6DAAqF;AACrF,gEAA2D;AAC3D,kDAA8D;AAG9D,gDAAwE;AAwCxE;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,gBAAgB,CAAC,MAItC;IACA,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC7C,IAAI,CAAC,IAAA,+BAAa,EAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,gCAAe,CACxB,8BAA8B,WAAW,CAAC,EAAE,oCAAoC,CAChF,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACtF,mFAAmF;IACnF,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CACnC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CACxB,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CACnF,CACD,CAAC;IACF,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACpB,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAC5E,CACD,CAAC;IACF,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO;QACN,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;KACxF,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,MAGnB;IACA,IAAI,MAA8D,CAAC;IACnE,OAAO,GAAG,EAAE;QACX,MAAM,KAAK,MAAM,CAAC,KAAK;aACrB,aAAa,EAAE;aACf,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC3D,OAAO,MAAM,CAAC;IACf,CAAC,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,SAAS,UAAU,CAAC,MAInB;IACA,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9F,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC3C,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACzD,OAAO,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtD,CAAC;IACD,MAAM,MAAM,GAAG,IAAA,4BAAe,EAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,MAAM,CAAC,MAA2D;IAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;AAChD,CAAC;AAiBD,mFAAmF;AACnF,KAAK,UAAU,UAAU,CAAC,MAAkB;IAC3C,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACzB,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;QACpC,GAAG,MAAM;QACT,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI;QACzB,KAAK,EAAE,KAAK,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,OAAO,CAAC,MAIhB;IACA,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACtC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,mDAAmD;AACnD,KAAK,UAAU,eAAe,CAAC,MAAkB;IAChD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,KAAK,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAC1F,CAAC;QACF,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACpC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAC/D,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,yFAAyF;AACzF,KAAK,UAAU,UAAU,CAAC,MAAkB;IAC3C,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAClE,MAAM,MAAM,GAAG,IAAA,0BAAW,EAAC,IAAI,CAAC,CAAC;IACjC,IAAI,MAAM,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,IAAA,sBAAY,EAAC;YAChC,KAAK,EAAE;gBACN,GAAG,KAAK,CAAC,KAAK;gBACd,QAAQ,EAAE,WAAW,CAAC,EAAE;gBACxB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,GAAG,EAAE;oBACJ,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,MAAM,EAAE,UAAU,CAAC,MAAM,MAAM,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC;iBAC7C;aACD;YACD,OAAO,EAAE,MAAM;YACf,KAAK;SACL,CAAC,CAAC;QACH,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,CAAC;IACD,OAAO,WAAW,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACzF,CAAC;AAED,0FAA0F;AAC1F,SAAS,UAAU,CAClB,MAAyC,EACzC,GAAW;IAEX,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CAAC,MAK1B;IACA,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,SAAS,CAAC,CAAC,CAAC;YAChB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACrD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACtB,OAAO,UAAU,CAAC;YACnB,CAAC;YACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpE,OAAO,aAAa,CAAC;YACtB,CAAC;YACD,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,KAAK,MAAM;YACV,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,KAAK,MAAM;YACV,OAAO,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAChF,KAAK,OAAO,CAAC;QACb,KAAK,UAAU,CAAC;QAChB,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS;YACb,OAAO,SAAS,CAAC;QAClB;YACC,OAAO,IAAA,0BAAkB,EAAC,IAAI,CAAC,CAAC;IAClC,CAAC;AACF,CAAC;AAED,wDAAwD;AACxD,SAAS,UAAU,CAAC,OAAwB;IAC3C,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;AACrE,CAAC;AAED,SAAS,eAAe,CAAC,GAAW,EAAE,KAAsB;IAC3D,MAAM,cAAc,GAAG,kCAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IAC7D,MAAM,WAAW,GAChB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;QACrC,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE;QACzB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAClD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC;AACjD,CAAC"}