@kelpie/server 0.5.1 → 0.6.0

package/dist/lib/fromEnv.js

@@ -0,0 +1,94 @@
+/**
+ * A marker a `kelpie.config.ts` file uses to say "read this leaf from the
+ * environment." The assembly's config file is the shape and the defaults;
+ * `fromEnv` marks the leaves a deployment may override without a code change.
+ *
+ * Every marker names an env var, the Zod schema that parses it, and optionally
+ * a default. Without a default the marker is required: the env var must be set,
+ * or boot fails with the other configuration problems.
+ *
+ * The resolver walks the config object, replaces each marker with the parsed
+ * value, and returns the fully-resolved object. Nothing in the app reads
+ * `process.env` for these fields after boot.
+ */
+const FROM_ENV_MARKER = Symbol.for('kelpie.fromEnv');
+export function fromEnv(envKey, schema, defaultValue) {
+    const hasDefault = arguments.length >= 3;
+    return {
+        [FROM_ENV_MARKER]: true,
+        envKey,
+        schema,
+        defaultValue: hasDefault ? defaultValue : undefined,
+        hasDefault,
+    };
+}
+export function isFromEnvMarker(value) {
+    return typeof value === 'object' && value !== null && value[FROM_ENV_MARKER] === true;
+}
+/**
+ * Resolves one marker against an environment.
+ *
+ * Missing and no default: one required problem.
+ * Missing with default: the default, unvalidated. A hardcoded default is
+ * trusted because the developer wrote it in the assembly file.
+ * Present: parsed through the marker's schema. Parse failures become problems.
+ */
+export function resolveMarker(marker, environment, path) {
+    const raw = environment[marker.envKey];
+    if (raw === undefined) {
+        if (marker.hasDefault) {
+            return { value: marker.defaultValue, problems: [] };
+        }
+        return {
+            value: undefined,
+            problems: [{ path, message: `${marker.envKey} is required` }],
+        };
+    }
+    const result = marker.schema.safeParse(raw);
+    if (!result.success) {
+        return {
+            value: undefined,
+            problems: result.error.issues.map((issue) => ({
+                path,
+                message: `${marker.envKey}: ${issue.message}`,
+            })),
+        };
+    }
+    return { value: result.data, problems: [] };
+}
+/**
+ * Walks any value, replacing every `FromEnvMarker` with its resolved value.
+ * Objects and arrays are walked recursively; other values pass through.
+ *
+ * Collects problems from every marker rather than throwing at the first one,
+ * so a self-hoster fixes their environment once rather than a variable at a
+ * time.
+ */
+export function resolveMarkers(input, environment, path = '') {
+    if (isFromEnvMarker(input)) {
+        return resolveMarker(input, environment, path);
+    }
+    if (Array.isArray(input)) {
+        const problems = [];
+        const value = input.map((item, index) => {
+            const childPath = `${path}[${String(index)}]`;
+            const result = resolveMarkers(item, environment, childPath);
+            problems.push(...result.problems);
+            return result.value;
+        });
+        return { value, problems };
+    }
+    if (typeof input === 'object' && input !== null) {
+        const problems = [];
+        const value = {};
+        for (const [key, child] of Object.entries(input)) {
+            const childPath = path.length > 0 ? `${path}.${key}` : key;
+            const result = resolveMarkers(child, environment, childPath);
+            problems.push(...result.problems);
+            value[key] = result.value;
+        }
+        return { value, problems };
+    }
+    return { value: input, problems: [] };
+}
+//# sourceMappingURL=fromEnv.js.map

package/dist/lib/fromEnv.js.map

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

package/dist/lib/ids.d.ts

@@ -50,6 +50,12 @@ export declare const idPrefixes: {
      * a bucket is bookkeeping the rate limiter owns, not a resource with routes.
      */
     readonly rateLimitBucket: 'rl';
+    /**
+     * One published domain event. Stamped on the envelope so downstream consumers
+     * (webhooks, MCP subscribers, an eventual outbox) have a stable idempotency
+     * key. Not persisted by core.
+     */
+    readonly event: 'ev';
 };
 export type ObjectKind = keyof typeof idPrefixes;
 export type IdFactory = (kind: ObjectKind) => string;

package/dist/lib/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,UAAU;aACrB,SAAS,EAAE,IAAI;aACf,IAAI,EAAE,KAAK;aACX,OAAO,EAAE,KAAK;aACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;aACxF,sBAAsB,EAAE,KAAK;aAC7B,UAAU,EAAE,KAAK;aACjB,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,OAAO,EAAE,KAAK;aACd,QAAQ,EAAE,KAAK;aACf,aAAa,EAAE,OAAO;aACtB,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,KAAK;aAClB,WAAW,EAAE,KAAK;aAClB,KAAK,EAAE,KAAK;aACZ,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,KAAK;aACf,IAAI,EAAE,MAAM;aACZ,QAAQ,EAAE,KAAK;aACf,YAAY,EAAE,IAAI;aAClB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,IAAI;aACf,cAAc,EAAE,KAAK;aACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;aAC9E,eAAe,EAAE,KAAK;aACtB,iBAAiB,EAAE,IAAI;aACvB,QAAQ,EAAE,KAAK;aACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;aAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;aACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;aACH,eAAe,EAAE,IAAI;CACb,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAA;AAEhD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,GAAE,MAAM,MAAa,GAAG,SAAS,CAE5E"}
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,UAAU;aACrB,SAAS,EAAE,IAAI;aACf,IAAI,EAAE,KAAK;aACX,OAAO,EAAE,KAAK;aACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;aACxF,sBAAsB,EAAE,KAAK;aAC7B,UAAU,EAAE,KAAK;aACjB,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,OAAO,EAAE,KAAK;aACd,QAAQ,EAAE,KAAK;aACf,aAAa,EAAE,OAAO;aACtB,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,KAAK;aAClB,WAAW,EAAE,KAAK;aAClB,KAAK,EAAE,KAAK;aACZ,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,KAAK;aACf,IAAI,EAAE,MAAM;aACZ,QAAQ,EAAE,KAAK;aACf,YAAY,EAAE,IAAI;aAClB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,IAAI;aACf,cAAc,EAAE,KAAK;aACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;aAC9E,eAAe,EAAE,KAAK;aACtB,iBAAiB,EAAE,IAAI;aACvB,QAAQ,EAAE,KAAK;aACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;aAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;aACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;aACH,eAAe,EAAE,IAAI;IACrB;;;;OAIG;aACH,KAAK,EAAE,IAAI;CACH,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAA;AAEhD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,GAAE,MAAM,MAAa,GAAG,SAAS,CAE5E"}

package/dist/lib/ids.js

@@ -51,6 +51,12 @@ export const idPrefixes = {
      * a bucket is bookkeeping the rate limiter owns, not a resource with routes.
      */
     rateLimitBucket: 'rl',
+    /**
+     * One published domain event. Stamped on the envelope so downstream consumers
+     * (webhooks, MCP subscribers, an eventual outbox) have a stable idempotency
+     * key. Not persisted by core.
+     */
+    event: 'ev',
 };
 /**
  * Builds the id factory. The ULID generator is injected so tests can pin ids;

package/dist/lib/ids.js.map

@@ -1 +1 @@
-{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,IAAI;IACf,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;IACxF,sBAAsB,EAAE,KAAK;IAC7B,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,OAAO;IACtB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,IAAI;IAClB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,KAAK;IACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;IAC9E,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,IAAI;IACvB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;IAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;IACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;IACH,eAAe,EAAE,IAAI;CACb,CAAA;AAMV;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAY,GAAiB,IAAI;IAC/D,OAAO,CAAC,IAAgB,EAAU,EAAE,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,EAAE,EAAE,CAAA;AAC9E,CAAC"}
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,IAAI;IACf,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;IACxF,sBAAsB,EAAE,KAAK;IAC7B,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,OAAO;IACtB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,IAAI;IAClB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,KAAK;IACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;IAC9E,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,IAAI;IACvB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;IAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;IACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;IACH,eAAe,EAAE,IAAI;IACrB;;;;OAIG;IACH,KAAK,EAAE,IAAI;CACH,CAAA;AAMV;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAY,GAAiB,IAAI;IAC/D,OAAO,CAAC,IAAgB,EAAU,EAAE,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,EAAE,EAAE,CAAA;AAC9E,CAAC"}

package/dist/lib/kelpieConfigFile.d.ts

@@ -0,0 +1,123 @@
+import type { KelpieModule } from '../runtime/module.ts';
+import { type Environment, type KelpieConfig, type LogLevel, type RuntimeMode } from './config.ts';
+import { type ConfigValue } from './fromEnv.ts';
+import type { LoggingDestination } from './logger.ts';
+/**
+ * The shape a `kelpie.config.ts` file declares.
+ *
+ * Every leaf is either a literal value the assembly commits to git, or a
+ * `fromEnv(...)` marker the deployment fills in. The resolver walks this
+ * object, replaces markers with parsed values, and returns a fully-populated
+ * `KelpieConfig`.
+ *
+ * The file is the map. `fromEnv(...)` marks the leaves a deployment overrides.
+ * Nothing in the app reads `process.env` for these fields after boot.
+ */
+export interface KelpieConfigInput {
+    readonly runtimeMode: ConfigValue<RuntimeMode>;
+    readonly port: ConfigValue<number>;
+    readonly databaseUrl: ConfigValue<string>;
+    readonly logging: LoggingInput;
+    /** Optional; unset in development, set to the built web bundle in a deployment. */
+    readonly webBundleDirectory?: ConfigValue<string | undefined>;
+    /** Optional; unset in development, set to the deploy-time module override file. */
+    readonly moduleConfigPath?: ConfigValue<string | undefined>;
+    /** Optional; defaults to 0 (no proxy in front). */
+    readonly trustedProxyHopCount?: ConfigValue<number>;
+    /**
+     * The deployment's base URL. Every emailed link (password reset, email
+     * verification, invite) is built from it. Required by the workspace and auth
+     * modules. Optional here so an older assembly can omit it and let those
+     * modules fall back to the `context.config(appUrlConfigSchema)` path.
+     */
+    readonly appBaseUrl?: ConfigValue<string>;
+    /**
+     * Keys that seal stored secrets (webhook signing secrets, agent-task auth
+     * headers). Required by the webhooks and agent-tasks modules. Optional here
+     * for the same reason `appBaseUrl` is.
+     */
+    readonly secretEncryption?: SecretEncryptionInput;
+    readonly email: EmailInput;
+    /** Optional; each unset field falls back to the same defaults `loadConfig` used. */
+    readonly rateLimit?: RateLimitInput;
+    /**
+     * Env-keyed values the assembly can lock in code, or defer to the
+     * environment. Modules read this through `context.config(schema)`; each
+     * module's own Zod schema still names the keys and validates them.
+     *
+     * A key present here overrides the same key in `process.env`. A key absent
+     * here falls through to `process.env` unchanged, so the section is a
+     * progressive migration: lock what you want to lock, leave the rest.
+     *
+     * Literal: `SECRET_ENCRYPTION_KEY: 'a-committed-key'` (don't do this for
+     * secrets — the point is you can, if the value is not a secret).
+     * Marker: `SECRET_ENCRYPTION_KEY: fromEnv('SECRET_ENCRYPTION_KEY', z.string())`
+     * defers to the environment, same as today.
+     */
+    readonly env?: Readonly<Record<string, ConfigValue<string | undefined>>>;
+    /** The module list the assembly composes. Same shape it had before. */
+    readonly modules: readonly KelpieModule[];
+}
+/**
+ * The `logging` sub-tree of the assembly config.
+ *
+ * `level` is the minimum severity to emit. `destinations` is the ordered list
+ * of destinations each line writes to; stdout is the default entry in the
+ * template assembly, and a self-hoster adds another by extending
+ * `LoggingDestination` in `@kelpie/server` and putting a matching entry here.
+ */
+export interface LoggingInput {
+    readonly level: ConfigValue<LogLevel>;
+    readonly destinations: readonly LoggingDestination[];
+}
+/**
+ * The `email` sub-tree of the assembly config.
+ *
+ * `provider` names one entry in the runtime's provider registry. `'log'` is a
+ * built-in the runtime always registers; `'smtp'` is registered by the
+ * built-in `smtp-email` core module; third-party provider modules register
+ * their own names (an API-based provider might register `'resend'` or
+ * `'postmark'`, and so on). Free-string so a self-hoster can install a
+ * module core has never heard of.
+ *
+ * `from` is the address on every outgoing message. Provider-specific config
+ * (SMTP host and credentials, an API key) belongs to the provider module,
+ * which reads it through `context.config(...)`; putting it here would tie the
+ * assembly config to a single transport.
+ */
+export interface EmailInput {
+    readonly provider: ConfigValue<string>;
+    readonly from: ConfigValue<string>;
+}
+export interface SecretEncryptionInput {
+    readonly key: ConfigValue<string>;
+    /** Absent (or blank) is normal; only set while rotating away from an older key. */
+    readonly previousKey?: ConfigValue<string | undefined>;
+}
+export interface RateLimitBudgetInput {
+    readonly limit?: ConfigValue<number>;
+    readonly windowSeconds?: ConfigValue<number>;
+}
+export interface RateLimitInput {
+    readonly forms?: RateLimitBudgetInput;
+    readonly auth?: RateLimitBudgetInput;
+    readonly loginAccount?: RateLimitBudgetInput;
+    readonly api?: RateLimitBudgetInput;
+}
+/**
+ * Identity helper for the assembly's config file. It exists for the type-check
+ * only: `defineKelpieConfig({...})` makes TypeScript check the object against
+ * `KelpieConfigInput` at the call site, so a wrong-shape field is caught in
+ * the assembly rather than at boot.
+ */
+export declare function defineKelpieConfig(input: KelpieConfigInput): KelpieConfigInput;
+/**
+ * Resolves an assembly's config against an environment.
+ *
+ * Every `fromEnv` marker is resolved. Missing required variables and parse
+ * failures are collected together, so a self-hoster fixes them in one pass.
+ *
+ * @throws ConfigurationError listing every problem.
+ */
+export declare function resolveKelpieConfig(input: KelpieConfigInput, environment: Environment): KelpieConfig;
+//# sourceMappingURL=kelpieConfigFile.d.ts.map

package/dist/lib/kelpieConfigFile.d.ts.map

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

package/dist/lib/kelpieConfigFile.js

@@ -0,0 +1,111 @@
+import { ConfigurationError } from './config.js';
+import { resolveMarkers } from './fromEnv.js';
+/**
+ * The defaults for each rate-limit budget, from `lib/rateLimit.ts`. Kept in
+ * this file so the assembly can leave `rateLimit` unset and still get the same
+ * numbers `loadConfig` produced.
+ */
+const RATE_LIMIT_DEFAULTS = {
+    forms: { limit: 20, windowSeconds: 60 },
+    auth: { limit: 10, windowSeconds: 60 },
+    loginAccount: { limit: 10, windowSeconds: 900 },
+    api: { limit: 600, windowSeconds: 60 },
+};
+/**
+ * Identity helper for the assembly's config file. It exists for the type-check
+ * only: `defineKelpieConfig({...})` makes TypeScript check the object against
+ * `KelpieConfigInput` at the call site, so a wrong-shape field is caught in
+ * the assembly rather than at boot.
+ */
+export function defineKelpieConfig(input) {
+    return input;
+}
+/**
+ * Resolves an assembly's config against an environment.
+ *
+ * Every `fromEnv` marker is resolved. Missing required variables and parse
+ * failures are collected together, so a self-hoster fixes them in one pass.
+ *
+ * @throws ConfigurationError listing every problem.
+ */
+export function resolveKelpieConfig(input, environment) {
+    const walked = resolveMarkers(input, environment);
+    const problems = [...walked.problems.map((problem) => (problem.path.length > 0 ? `${problem.path}: ${problem.message}` : problem.message))];
+    // Even when problems exist, the walk still produced a partial object. Reshape
+    // it now: any field a problem covered will be undefined, which is fine, since
+    // we throw before returning.
+    const resolved = walked.value;
+    const email = buildEmailConfig(resolved.email);
+    const rateLimit = buildRateLimitConfig(resolved.rateLimit);
+    const env = mergeEnv(environment, resolved.env);
+    const secretEncryption = buildSecretEncryptionConfig(resolved.secretEncryption);
+    if (problems.length > 0) {
+        throw new ConfigurationError(problems);
+    }
+    return {
+        runtimeMode: resolved.runtimeMode,
+        port: resolved.port,
+        databaseUrl: resolved.databaseUrl,
+        logging: {
+            level: resolved.logging.level,
+            destinations: resolved.logging.destinations,
+        },
+        email,
+        moduleConfigPath: resolved.moduleConfigPath,
+        webBundleDirectory: resolved.webBundleDirectory,
+        rateLimit,
+        trustedProxyHopCount: resolved.trustedProxyHopCount ?? 0,
+        env,
+        appBaseUrl: resolved.appBaseUrl,
+        secretEncryption,
+    };
+}
+/**
+ * `kelpie.config.ts` env wins per-key; unset keys pass through from `environment`.
+ * Absent env section returns `environment` unchanged, so a self-hoster who has
+ * not opted in gets the same behaviour they had before pass 2.
+ */
+function mergeEnv(environment, resolvedEnv) {
+    if (resolvedEnv === undefined) {
+        return environment;
+    }
+    return { ...environment, ...resolvedEnv };
+}
+function buildEmailConfig(resolved) {
+    // Missing `email.provider` or `email.from` is already recorded by the
+    // walker; return a placeholder so `resolveKelpieConfig` reaches its throw
+    // below.
+    return {
+        EMAIL_PROVIDER: resolved?.provider ?? '',
+        EMAIL_FROM: resolved?.from ?? '',
+    };
+}
+/**
+ * Reshape the resolved leaves into the `SecretEncryptionConfig` shape modules
+ * already consume. Returns undefined when the config file omits the field, in
+ * which case a module falls back to reading `context.config(...)`.
+ */
+function buildSecretEncryptionConfig(resolved) {
+    if (resolved === undefined) {
+        return undefined;
+    }
+    return resolved.previousKey === undefined
+        ? { SECRET_ENCRYPTION_KEY: resolved.key }
+        : { SECRET_ENCRYPTION_KEY: resolved.key, SECRET_ENCRYPTION_KEY_PREVIOUS: resolved.previousKey };
+}
+function buildRateLimitConfig(resolved) {
+    return {
+        forms: budget('forms', resolved?.forms),
+        auth: budget('auth', resolved?.auth),
+        loginAccount: budget('loginAccount', resolved?.loginAccount),
+        api: budget('api', resolved?.api),
+    };
+}
+function budget(key, input) {
+    const defaults = RATE_LIMIT_DEFAULTS[key];
+    return {
+        limit: input?.limit ?? defaults.limit,
+        windowMs: (input?.windowSeconds ?? defaults.windowSeconds) * 1000,
+    };
+}
+//# sourceMappingURL=kelpieConfigFile.js.map

package/dist/lib/kelpieConfigFile.js.map

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

package/dist/lib/logger.d.ts

@@ -1,7 +1,15 @@
+import Transport from 'winston-transport';
 import type { LogLevel } from './config.ts';
 /**
- * Structured logging as JSON lines. The sink is injected so tests capture output
- * instead of writing to stdout, and so a deployment can redirect it.
+ * Structured logging as JSON lines. Every line goes through one or more
+ * transports, each of which is a named destination (`createStdoutTransport`,
+ * `createCaptureTransport`, and whatever a deployment adds). Nothing defaults:
+ * an empty transport list means the logger writes nowhere, which the assembly
+ * must notice.
+ *
+ * Winston handles level filtering and fan-out to transports. The JSON line
+ * itself is built in this file and passed through as the message, so the
+ * envelope order (`time`, `level`, `message` last) is preserved exactly.
  */
 export type LogFields = Readonly<Record<string, unknown>>;
 export interface Logger {
@@ -12,11 +20,34 @@ export interface Logger {
     /** Returns a logger that stamps `fields` onto every line, e.g. a request id. */
     child(fields: LogFields): Logger;
 }
-export type LogSink = (line: string) => void;
 /**
- * @param level Minimum level to emit. Lines below it are dropped.
- * @param sink Receives one complete JSON line per log call.
- * @param now Injected so tests get deterministic timestamps.
+ * A destination declared in `kelpie.config.ts`. Extend the union to add a new
+ * kind; the switch in `createTransportForDestination` fails to compile until it
+ * covers every new variant, so a destination cannot be added in config without
+ * a matching transport factory.
  */
-export declare function createLogger(level: LogLevel, sink?: LogSink, now?: () => Date): Logger;
+export type LoggingDestination = {
+    readonly kind: 'stdout';
+};
+/** Writes each line plus a trailing newline directly to stdout. */
+export declare function createStdoutTransport(): Transport;
+/** Hands each line to a callback. Tests use it to capture output. */
+export declare function createCaptureTransport(onLine: (line: string) => void): Transport;
+/**
+ * Builds the transport for one declared destination. The switch is exhaustive
+ * so adding a new `LoggingDestination` kind without a factory clause fails to
+ * compile.
+ */
+export declare function createTransportForDestination(destination: LoggingDestination): Transport;
+export interface CreateLoggerOptions {
+    readonly level: LogLevel;
+    readonly transports: readonly Transport[];
+    /** Injected so tests get deterministic timestamps. Defaults to the wall clock. */
+    readonly now?: () => Date;
+}
+/**
+ * Builds a logger. `transports` is required: an empty list writes nowhere and
+ * that is the assembly's decision to make, not a silent default.
+ */
+export declare function createLogger(options: CreateLoggerOptions): Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEzD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,gFAAgF;IAChF,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAA;CACjC;AAED,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAa5C;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,EACf,IAAI,GAAE,OAAuB,EAC7B,GAAG,GAAE,MAAM,IAAuB,GACjC,MAAM,CAgCR"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AACA,OAAO,SAAS,MAAM,mBAAmB,CAAA;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEzD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,gFAAgF;IAChF,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAA;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAyB5D,mEAAmE;AACnE,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD;AAED,qEAAqE;AACrE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,SAAS,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,kBAAkB,GAAG,SAAS,CAKxF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;IACzC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAoCjE"}

package/dist/lib/logger.js

@@ -1,34 +1,72 @@
-const severityByLevel = {
-    debug: 10,
-    info: 20,
-    warn: 30,
-    error: 40,
+import winston from 'winston';
+import Transport from 'winston-transport';
+const LEVELS = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
 };
-function writeToStdout(line) {
-    process.stdout.write(`${line}\n`);
+class LineTransport extends Transport {
+    writeLine;
+    constructor(writeLine) {
+        super();
+        this.writeLine = writeLine;
+    }
+    log(info, next) {
+        this.writeLine(info.message);
+        // Winston expects the transport to emit 'logged' after handling.
+        setImmediate(() => this.emit('logged', info));
+        next();
+    }
+}
+/** Writes each line plus a trailing newline directly to stdout. */
+export function createStdoutTransport() {
+    return new LineTransport((line) => {
+        process.stdout.write(`${line}\n`);
+    });
+}
+/** Hands each line to a callback. Tests use it to capture output. */
+export function createCaptureTransport(onLine) {
+    return new LineTransport(onLine);
+}
+/**
+ * Builds the transport for one declared destination. The switch is exhaustive
+ * so adding a new `LoggingDestination` kind without a factory clause fails to
+ * compile.
+ */
+export function createTransportForDestination(destination) {
+    switch (destination.kind) {
+        case 'stdout':
+            return createStdoutTransport();
+    }
 }
 /**
- * @param level Minimum level to emit. Lines below it are dropped.
- * @param sink Receives one complete JSON line per log call.
- * @param now Injected so tests get deterministic timestamps.
+ * Builds a logger. `transports` is required: an empty list writes nowhere and
+ * that is the assembly's decision to make, not a silent default.
  */
-export function createLogger(level, sink = writeToStdout, now = () => new Date()) {
-    const threshold = severityByLevel[level];
+export function createLogger(options) {
+    const now = options.now ?? (() => new Date());
+    const winstonLogger = winston.createLogger({
+        levels: LEVELS,
+        level: options.level,
+        transports: [...options.transports],
+    });
     function build(boundFields) {
         function emit(lineLevel, message, fields) {
-            if (severityByLevel[lineLevel] < threshold) {
-                return;
-            }
-            // The envelope is written last so a field called `message`, `level`, or
-            // `time` cannot overwrite it. A colliding field is dropped; a corrupted
-            // envelope would make the whole line untrustworthy.
-            sink(JSON.stringify({
+            // The envelope is written last so a bound or per-call field called
+            // `message`, `level`, or `time` cannot overwrite it. A colliding field
+            // is dropped; a corrupted envelope would make the whole line untrustworthy.
+            const line = JSON.stringify({
                 ...boundFields,
                 ...fields,
                 time: now().toISOString(),
                 level: lineLevel,
                 message,
-            }));
+            });
+            // The full JSON line is passed as `message` and each transport writes it
+            // verbatim. Winston still filters by level and fans out to transports;
+            // it does not re-format the line.
+            winstonLogger.log({ level: lineLevel, message: line });
         }
         return {
             debug: (message, fields) => emit('debug', message, fields),

package/dist/lib/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAoBA,MAAM,eAAe,GAAuC;IAC1D,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAA;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAA;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAe,EACf,IAAI,GAAY,aAAa,EAC7B,GAAG,GAAe,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAElC,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IAExC,SAAS,KAAK,CAAC,WAAsB;QACnC,SAAS,IAAI,CAAC,SAAmB,EAAE,OAAe,EAAE,MAAkB;YACpE,IAAI,eAAe,CAAC,SAAS,CAAC,GAAG,SAAS,EAAE,CAAC;gBAC3C,OAAM;YACR,CAAC;YACD,wEAAwE;YACxE,wEAAwE;YACxE,oDAAoD;YACpD,IAAI,CACF,IAAI,CAAC,SAAS,CAAC;gBACb,GAAG,WAAW;gBACd,GAAG,MAAM;gBACT,IAAI,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE;gBACzB,KAAK,EAAE,SAAS;gBAChB,OAAO;aACR,CAAC,CACH,CAAA;QACH,CAAC;QAED,OAAO;YACL,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;YAC1D,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;YACxD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;YACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;YAC1D,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,WAAW,EAAE,GAAG,MAAM,EAAE,CAAC;SACxD,CAAA;IACH,CAAC;IAED,OAAO,KAAK,CAAC,EAAE,CAAC,CAAA;AAClB,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"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"}

package/dist/modules/agent-tasks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-tasks/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAKjD;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAC7B;AAED,wBAAgB,sBAAsB,CACpC,mBAAmB,EAAE,MAAM,EAC3B,OAAO,GAAE,uBAA4B,GACpC,YAAY,CAsDd"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-tasks/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAKjD;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAC7B;AAED,wBAAgB,sBAAsB,CACpC,mBAAmB,EAAE,MAAM,EAC3B,OAAO,GAAE,uBAA4B,GACpC,YAAY,CAyDd"}

package/dist/modules/agent-tasks/index.js

@@ -27,7 +27,10 @@ export function createAgentTasksModule(migrationsDirectory, options = {}) {
             // Validated at boot rather than on the first run: a missing or malformed
             // key means no stored auth header can ever be read back, and finding that
             // out when a dispatch quietly fails is far too late.
-            const cipher = createSecretCipher(context.config(secretEncryptionConfigSchema));
+            //
+            // Prefer the top-level `secretEncryption` from the assembly's
+            // kelpie.config.ts; fall back to the schema read for older assemblies.
+            const cipher = createSecretCipher(context.secretEncryption ?? context.config(secretEncryptionConfigSchema));
             const egress = createEgressGuard(context.config(egressConfigSchema));
             const engine = createDispatchEngine({
                 db: context.db,

package/dist/modules/agent-tasks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/agent-tasks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAA;AAEvF,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAgBtD,MAAM,UAAU,sBAAsB,CACpC,mBAA2B,EAC3B,OAAO,GAA4B,EAAE;IAErC,OAAO;QACL,EAAE,EAAE,aAAa;QACjB,QAAQ,EAAE;YACR,WAAW;YACX,QAAQ;YACR,WAAW;YACX,WAAW;YACX,WAAW;YACX,OAAO;YACP,eAAe;YACf,cAAc;YACd,QAAQ;YACR,QAAQ;YACR,OAAO;YACP,WAAW;YACX,OAAO;YACP,UAAU;SACX;QAED,QAAQ,CAAC,OAAO;YACd,yEAAyE;YACzE,0EAA0E;YAC1E,qDAAqD;YACrD,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAA;YAC/E,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAA;YAEpE,MAAM,MAAM,GAAG,oBAAoB,CAAC;gBAClC,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,MAAM;gBACN,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;gBAC9C,GAAG,EAAE,OAAO,CAAC,GAAG;aACjB,CAAC,CAAA;YAEF,MAAM,OAAO,GAAG,uBAAuB,CAAC;gBACtC,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,MAAM;gBACN,MAAM;gBACN,GAAG,EAAE,OAAO,CAAC,GAAG;aACjB,CAAC,CAAA;YAEF,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;YAE3C,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;gBACxB,qBAAqB,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;YAC9E,CAAC,CAAC,CAAA;YAEF,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/agent-tasks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAA;AAEvF,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAgBtD,MAAM,UAAU,sBAAsB,CACpC,mBAA2B,EAC3B,OAAO,GAA4B,EAAE;IAErC,OAAO;QACL,EAAE,EAAE,aAAa;QACjB,QAAQ,EAAE;YACR,WAAW;YACX,QAAQ;YACR,WAAW;YACX,WAAW;YACX,WAAW;YACX,OAAO;YACP,eAAe;YACf,cAAc;YACd,QAAQ;YACR,QAAQ;YACR,OAAO;YACP,WAAW;YACX,OAAO;YACP,UAAU;SACX;QAED,QAAQ,CAAC,OAAO;YACd,yEAAyE;YACzE,0EAA0E;YAC1E,qDAAqD;YACrD,EAAE;YACF,8DAA8D;YAC9D,uEAAuE;YACvE,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAA;YAC3G,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAA;YAEpE,MAAM,MAAM,GAAG,oBAAoB,CAAC;gBAClC,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,MAAM;gBACN,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;gBAC9C,GAAG,EAAE,OAAO,CAAC,GAAG;aACjB,CAAC,CAAA;YAEF,MAAM,OAAO,GAAG,uBAAuB,CAAC;gBACtC,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,MAAM;gBACN,MAAM;gBACN,GAAG,EAAE,OAAO,CAAC,GAAG;aACjB,CAAC,CAAA;YAEF,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;YAE3C,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;gBACxB,qBAAqB,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;YAC9E,CAAC,CAAC,CAAA;YAEF,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;KACF,CAAA;AACH,CAAC"}