@agent-native/core 0.158.10 → 0.159.1

package/dist/app-config/app.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+/**
+ * App identity.
+ *
+ * Three fields, not one, because the eight environment keys that spell "which
+ * app is this" were never all the same question:
+ *
+ * - `id` is this deployment's own identity — data programs, onboarding, the
+ *   CLI, and agent model defaults scope by it.
+ * - `workspaceId` is the identity a workspace deploy assigns. `vault_grants`
+ *   rows are written with it, so credential scoping must prefer it over `id`
+ *   or an app would look up grants under a name nobody granted.
+ * - `name` is the user-facing display name ("Acme"), used in transactional
+ *   emails and page titles. It is not an identifier, and only leaks into
+ *   identity resolution as a last-resort fallback in readers that had nothing
+ *   better.
+ *
+ * Collapsing these into one field is the tempting simplification and it is
+ * wrong: it would silently repoint credential grant lookups.
+ *
+ * None of them has a default. `credentialProvider` denies access when no app
+ * identity is configured, and a default of `"app"` would turn that denial into
+ * a lookup scoped to an app literally named `app`. Readers that want a
+ * placeholder apply it themselves, where it is visible.
+ */
+export const appConfig = z.object({
+    id: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["AGENT_NATIVE_APP_ID", "APP_ID"],
+        doc: "Stable identity of this app deployment.",
+    }),
+    workspaceId: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: [
+            "AGENT_NATIVE_WORKSPACE_APP_ID",
+            "VITE_AGENT_NATIVE_WORKSPACE_APP_ID",
+        ],
+        doc: "Identity assigned by a workspace deploy. Credential grants are scoped to this.",
+    }),
+    name: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["APP_NAME"],
+        doc: "User-facing display name of this app.",
+    }),
+    /**
+     * The app's canonical public URL — what a user sees in a share link, an
+     * email, or a JWT issuer claim.
+     *
+     * This is NOT "where does this running deployment answer". On a deploy
+     * preview those differ, and conflating them is what sent background work to
+     * production from a preview twice. Self-address is derived by
+     * `resolveSelfDispatchBaseUrl()`, which consults the platform's own deploy
+     * URLs first and falls back to this; it is deliberately not settable here.
+     *
+     * Not `.url()`-validated on purpose. This value is read by self-dispatch,
+     * SSR, and OAuth, so a malformed one would make every `getAppConfig()` call
+     * in the process throw rather than fail in the one place that cares.
+     * Consumers that need a parseable URL validate it themselves and say what
+     * broke — `onboarding-html.ts` already reports "invalid app URL" with the
+     * feature named, which is a better error than a zod path.
+     */
+    url: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: [
+            "APP_URL",
+            "VITE_APP_URL",
+            "BETTER_AUTH_URL",
+            "VITE_BETTER_AUTH_URL",
+        ],
+        doc: "Canonical public URL of this app, used for user-facing links.",
+    }),
+    packageName: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["npm_package_name"],
+        doc: "Package name of the running app, as npm sets it for a script.",
+    }),
+    template: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["VITE_AGENT_NATIVE_TEMPLATE"],
+        doc: "First-party template this app was generated from.",
+    }),
+});

package/dist/app-config/describe.d.ts

@@ -0,0 +1,26 @@
+import type { ZodType } from "zod";
+/**
+ * Reflection over the config schema, for generators.
+ *
+ * The point of declaring configuration in one schema is that the docs, the
+ * documented-key sets, and the hosted-deploy allow-list can be derived from it
+ * instead of hand-maintained in four places. This module is what makes that
+ * derivation possible; `scripts/sync-config-docs.ts` is its first consumer.
+ */
+export interface ConfigFieldDescription {
+    /** Dotted path, e.g. `agent.engine`. */
+    path: string;
+    /** Declared environment aliases, in precedence order. Empty when none. */
+    env: string[];
+    /** Base type after modifiers are peeled off, e.g. `string`, `boolean`. */
+    type: string;
+    /** `doc` from `.meta()`, when the field declares one. */
+    doc?: string;
+    /** Declared default, already resolved if it was a factory. */
+    defaultValue?: unknown;
+    required: boolean;
+}
+/** Every leaf field in the schema, in declaration order. */
+export declare function describeConfigFields(schema?: ZodType): ConfigFieldDescription[];
+/** Every environment key the schema declares, deduplicated and sorted. */
+export declare function declaredEnvKeys(schema?: ZodType): string[];

package/dist/app-config/describe.js

@@ -0,0 +1,61 @@
+import { collectEnvAliases } from "./env-layer.js";
+import { appConfigSchema } from "./schema.js";
+function internals(schema) {
+    return schema._zod;
+}
+const WRAPPER_TYPES = new Set([
+    "optional",
+    "default",
+    "prefault",
+    "nullable",
+    "readonly",
+]);
+/** Every leaf field in the schema, in declaration order. */
+export function describeConfigFields(schema = appConfigSchema) {
+    const fields = [];
+    const visit = (node, path) => {
+        const meta = node.meta?.();
+        let inner = node;
+        let optional = false;
+        let defaultValue;
+        while (WRAPPER_TYPES.has(internals(inner).def.type)) {
+            const { type, innerType, defaultValue: declared } = internals(inner).def;
+            if (type === "optional" || type === "nullable")
+                optional = true;
+            if (type === "default" || type === "prefault") {
+                defaultValue = typeof declared === "function" ? declared() : declared;
+                optional = true;
+            }
+            if (innerType === undefined)
+                break;
+            inner = innerType;
+        }
+        const { type, shape } = internals(inner).def;
+        if (type === "object" && shape) {
+            for (const [key, child] of Object.entries(shape)) {
+                visit(child, [...path, key]);
+            }
+            return;
+        }
+        const env = meta?.env;
+        fields.push({
+            path: path.join("."),
+            env: typeof env === "string" ? [env] : Array.isArray(env) ? env : [],
+            type,
+            doc: typeof meta?.doc === "string" ? meta.doc : undefined,
+            defaultValue,
+            required: !optional,
+        });
+    };
+    visit(schema, []);
+    return fields;
+}
+/** Every environment key the schema declares, deduplicated and sorted. */
+export function declaredEnvKeys(schema = appConfigSchema) {
+    const keys = new Set();
+    for (const alias of collectEnvAliases(schema)) {
+        for (const key of alias.env)
+            keys.add(key);
+    }
+    return [...keys].sort();
+}

package/dist/app-config/env-layer.d.ts

@@ -0,0 +1,37 @@
+import type { ZodType } from "zod";
+/**
+ * Builds the environment-variable layer of the app config.
+ *
+ * Environment variables are declared shortcuts into the schema, not a parallel
+ * namespace: a key exists only because some field carries `.meta({ env })`.
+ * This module is the one place in the framework that turns those strings into
+ * typed values, which is what lets every consumer read `getAppConfig()`
+ * instead of parsing `process.env` at its own call site.
+ */
+/**
+ * A leaf field that declares one or more environment-variable aliases.
+ *
+ * `env` is ordered: the first key that is set wins. Several fields need this
+ * because one concept accumulated many spellings over time — app identity has
+ * eight — and collapsing them means declaring the precedence once here instead
+ * of rebuilding a slightly different chain at each call site.
+ */
+export interface EnvAlias {
+    path: string[];
+    env: string[];
+    type: string;
+}
+/** Every leaf in `schema` that declares an environment-variable alias. */
+export declare function collectEnvAliases(schema: ZodType): EnvAlias[];
+/**
+ * Reads every declared alias out of `env` into a partial config object.
+ *
+ * A key that is unset, empty, or only whitespace is treated as absent. Several
+ * hosting platforms surface an unset variable as `""`, and every reader this
+ * replaces used `?.trim() ||` — so a blank value has always meant "fall through
+ * to the next source", never "the configured value is blank".
+ *
+ * When a field declares several aliases, the first one with a value wins and
+ * the rest are not consulted.
+ */
+export declare function readEnvConfigLayer(schema: ZodType, env: Record<string, string | undefined>): Record<string, unknown>;

package/dist/app-config/env-layer.js

@@ -0,0 +1,136 @@
+/**
+ * Zod exposes no public API for peeling `.optional()` / `.default()` back off a
+ * field, and we need the declared kind underneath to know how to parse a string
+ * into it. `_zod.def` is that introspection surface; a zod major upgrade is the
+ * moment to re-check this file.
+ */
+function internals(schema) {
+    return schema._zod;
+}
+const WRAPPER_TYPES = new Set([
+    "optional",
+    "default",
+    "prefault",
+    "nullable",
+    "readonly",
+]);
+const MAX_WRAPPER_DEPTH = 10;
+function unwrap(schema, path) {
+    let node = schema;
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
+        const { type, innerType } = internals(node).def;
+        if (!WRAPPER_TYPES.has(type) || innerType === undefined)
+            return node;
+        node = innerType;
+    }
+    throw new Error(`Config field "${path.join(".")}" wraps more than ${MAX_WRAPPER_DEPTH} modifiers deep`);
+}
+function readEnvMeta(node) {
+    const meta = node.meta?.();
+    const env = meta?.env;
+    const keys = typeof env === "string" ? [env] : Array.isArray(env) ? env : [];
+    const valid = keys.filter((key) => typeof key === "string" && key.length > 0);
+    return valid.length > 0 ? valid : undefined;
+}
+// Walking the schema is pure and the schema is a module constant, so the walk
+// happens once per schema rather than on every config read.
+const aliasCache = new WeakMap();
+/** Every leaf in `schema` that declares an environment-variable alias. */
+export function collectEnvAliases(schema) {
+    const cached = aliasCache.get(schema);
+    if (cached)
+        return cached;
+    const aliases = [];
+    const visit = (node, path) => {
+        const env = readEnvMeta(node);
+        const base = unwrap(node, path);
+        const { type, shape } = internals(base).def;
+        if (type === "object" && shape) {
+            if (env) {
+                throw new Error(`Config group "${path.join(".")}" declares env "${env.join(", ")}". Only leaf fields can carry an environment alias.`);
+            }
+            for (const [key, child] of Object.entries(shape)) {
+                visit(child, [...path, key]);
+            }
+            return;
+        }
+        if (env)
+            aliases.push({ path, env, type });
+    };
+    visit(schema, []);
+    aliasCache.set(schema, aliases);
+    return aliases;
+}
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+function parseEnvValue(raw, key, alias) {
+    switch (alias.type) {
+        case "string":
+        case "enum":
+        case "literal":
+            // Every hand-rolled reader this replaces trimmed its value. Keeping that
+            // means a stray trailing space in a deploy UI does not become part of an
+            // app id or a URL.
+            return raw.trim();
+        case "boolean": {
+            const normalized = raw.trim().toLowerCase();
+            if (TRUE_VALUES.has(normalized))
+                return true;
+            if (FALSE_VALUES.has(normalized))
+                return false;
+            throw new Error(`${key} must be one of ${[...TRUE_VALUES, ...FALSE_VALUES].join(", ")}, got "${raw}"`);
+        }
+        case "number":
+        case "int": {
+            const value = Number(raw.trim());
+            if (!Number.isFinite(value)) {
+                throw new Error(`${key} must be a number, got "${raw}"`);
+            }
+            return value;
+        }
+        case "array":
+            // Comma-separated, which is what every hand-rolled list reader in core
+            // already used. Blank entries are dropped so a trailing comma is not an
+            // empty allow-list entry.
+            return raw
+                .split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean);
+        default:
+            throw new Error(`Config field "${alias.path.join(".")}" declares env "${key}" but its type "${alias.type}" has no environment parser. Add one here or drop the alias.`);
+    }
+}
+function assign(target, path, value) {
+    let node = target;
+    for (const key of path.slice(0, -1)) {
+        const existing = node[key];
+        if (existing === undefined)
+            node[key] = {};
+        node = node[key];
+    }
+    node[path[path.length - 1]] = value;
+}
+/**
+ * Reads every declared alias out of `env` into a partial config object.
+ *
+ * A key that is unset, empty, or only whitespace is treated as absent. Several
+ * hosting platforms surface an unset variable as `""`, and every reader this
+ * replaces used `?.trim() ||` — so a blank value has always meant "fall through
+ * to the next source", never "the configured value is blank".
+ *
+ * When a field declares several aliases, the first one with a value wins and
+ * the rest are not consulted.
+ */
+export function readEnvConfigLayer(schema, env) {
+    const layer = {};
+    for (const alias of collectEnvAliases(schema)) {
+        for (const key of alias.env) {
+            const raw = env[key];
+            if (raw === undefined || raw.trim() === "")
+                continue;
+            assign(layer, alias.path, parseEnvValue(raw, key, alias));
+            break;
+        }
+    }
+    return layer;
+}

package/dist/app-config/index.d.ts

@@ -0,0 +1,2 @@
+export { defineAppConfig, getAppConfig, resetAppConfigForTests, } from "./store.js";
+export { appConfigSchema, type AppConfig, type AppConfigInput, } from "./schema.js";

package/dist/app-config/index.js

@@ -0,0 +1,2 @@
+export { defineAppConfig, getAppConfig, resetAppConfigForTests, } from "./store.js";
+export { appConfigSchema, } from "./schema.js";

package/dist/app-config/integrations.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** Inbound integration webhook policy. */
+export declare const integrationsConfig: z.ZodObject<{
+    allowUnverifiedWebhooks: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;

package/dist/app-config/integrations.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/** Inbound integration webhook policy. */
+export const integrationsConfig = z.object({
+    allowUnverifiedWebhooks: z
+        .boolean()
+        .default(false)
+        .meta({
+        env: ["AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS"],
+        doc: "Skip inbound webhook signature verification. Development only — every adapter that reads this treats it as a bypass of sender authentication.",
+    }),
+});

package/dist/app-config/private-blob.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/**
+ * Private blob storage.
+ *
+ * `provider` names which registered provider is active. Leaving it unset keeps
+ * the historical rule — the first registered provider reporting itself
+ * configured — which is decided by module import order, so an app cannot state
+ * its choice, only hope its provider registered first. Set it explicitly
+ * whenever more than one provider can be configured in the same deployment.
+ */
+export declare const privateBlobConfig: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    publicUploadFallback: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;

package/dist/app-config/private-blob.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Private blob storage.
+ *
+ * `provider` names which registered provider is active. Leaving it unset keeps
+ * the historical rule — the first registered provider reporting itself
+ * configured — which is decided by module import order, so an app cannot state
+ * its choice, only hope its provider registered first. Set it explicitly
+ * whenever more than one provider can be configured in the same deployment.
+ */
+export const privateBlobConfig = z.object({
+    provider: z.string().min(1).optional().meta({
+        doc: "Id of the registered private blob provider to use. Unset falls back to the first registered provider that reports itself configured.",
+    }),
+    publicUploadFallback: z.boolean().default(true).meta({
+        env: "AGENT_NATIVE_PRIVATE_BLOB_PUBLIC_UPLOAD_FALLBACK",
+        doc: "Store private blobs as encrypted objects in public file-upload storage when no private blob provider is configured.",
+    }),
+});

package/dist/app-config/schema.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+/**
+ * The server-side configurable surface of the framework, in one schema.
+ *
+ * One object of optional per-domain subobjects. A domain adds a file next to
+ * this one and a single line here; nothing else has to learn about it.
+ *
+ * This object is never serialized. Client-visible configuration is a different
+ * object with a different lifetime — `AgentNativeConfig` in `src/config.ts`,
+ * resolved at build time and projected into the bundle. Anything that must not
+ * reach a browser belongs here, not there.
+ */
+export declare const appConfigSchema: z.ZodObject<{
+    a2a: z.ZodPrefault<z.ZodObject<{
+        allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowUnsignedInternal: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    agent: z.ZodPrefault<z.ZodObject<{
+        engine: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodString>;
+        preferBringYourOwnKey: z.ZodDefault<z.ZodBoolean>;
+        runSoftTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        completedRunRetentionMs: z.ZodOptional<z.ZodNumber>;
+        erroredRunRetentionMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    app: z.ZodPrefault<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        workspaceId: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        packageName: z.ZodOptional<z.ZodString>;
+        template: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    integrations: z.ZodPrefault<z.ZodObject<{
+        allowUnverifiedWebhooks: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    privateBlob: z.ZodPrefault<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        publicUploadFallback: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    workspace: z.ZodPrefault<z.ZodObject<{
+        gatewayUrl: z.ZodOptional<z.ZodString>;
+        oauthOrigin: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Accepted by `defineAppConfig`.
+ *
+ * Distinct from `AppConfig` because a field with `.default()` is optional on
+ * the way in and guaranteed present on the way out.
+ */
+export type AppConfigInput = z.input<typeof appConfigSchema>;
+/** Returned by `getAppConfig`, with declared defaults applied. */
+export type AppConfig = z.output<typeof appConfigSchema>;

package/dist/app-config/schema.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { a2aConfig } from "./a2a.js";
+import { agentConfig } from "./agent.js";
+import { appConfig } from "./app.js";
+import { integrationsConfig } from "./integrations.js";
+import { privateBlobConfig } from "./private-blob.js";
+import { workspaceConfig } from "./workspace.js";
+/**
+ * The server-side configurable surface of the framework, in one schema.
+ *
+ * One object of optional per-domain subobjects. A domain adds a file next to
+ * this one and a single line here; nothing else has to learn about it.
+ *
+ * This object is never serialized. Client-visible configuration is a different
+ * object with a different lifetime — `AgentNativeConfig` in `src/config.ts`,
+ * resolved at build time and projected into the bundle. Anything that must not
+ * reach a browser belongs here, not there.
+ */
+// Every domain wraps in `.prefault({})`, not `.optional()` or `.default({})`.
+// An optional domain never materializes the defaults declared inside it, and
+// `.default({})` hands back the literal `{}` without parsing it — both leave
+// readers with `undefined` where the type promises a value. `.prefault` runs
+// the domain schema over the empty object, so a declared default is there.
+export const appConfigSchema = z.object({
+    a2a: a2aConfig.prefault({}),
+    agent: agentConfig.prefault({}),
+    app: appConfig.prefault({}),
+    integrations: integrationsConfig.prefault({}),
+    privateBlob: privateBlobConfig.prefault({}),
+    workspace: workspaceConfig.prefault({}),
+});

package/dist/app-config/store.d.ts

@@ -0,0 +1,42 @@
+import { type AppConfig, type AppConfigInput } from "./schema.js";
+/**
+ * Resolution order for app configuration, lowest opinion first.
+ *
+ * `legacy` is where the bespoke `configure*` / `set*` setters this schema
+ * replaces write their values, so a deprecated call still works and still has
+ * a stated position rather than whichever `if` happens to run first.
+ */
+declare const LAYER_ORDER: readonly ["env", "legacy", "app"];
+export type AppConfigLayer = (typeof LAYER_ORDER)[number];
+/**
+ * Writes one layer of the ladder. Framework-internal: the deprecated setters
+ * use it to keep working without reintroducing a second namespace.
+ */
+export declare function setAppConfigLayer(layer: AppConfigLayer, config: AppConfigInput): void;
+/**
+ * Sets this app's server configuration.
+ *
+ * Call it from a server plugin. Values given here beat any environment
+ * variable aliased to the same field. Calling it more than once merges, so an
+ * app can split its configuration by domain across plugin files.
+ */
+export declare function defineAppConfig(config: AppConfigInput): void;
+/**
+ * The resolved configuration, with declared defaults applied.
+ *
+ * The parsed result is cached, but the env layer is rebuilt each call and the
+ * cache is dropped when it differs. Re-reading a handful of declared keys is
+ * cheap next to re-parsing the schema, and caching the env read outright would
+ * mean whichever code path ran first froze the configuration for the process —
+ * a stale value nobody can see, which is the failure this module exists to
+ * remove.
+ */
+export declare function getAppConfig(): AppConfig;
+/**
+ * Drops every layer and the resolved cache.
+ *
+ * The resolved object is cached on first read, so a test that mutates
+ * `process.env` between cases has to call this to be seen.
+ */
+export declare function resetAppConfigForTests(): void;
+export {};

package/dist/app-config/store.js

@@ -0,0 +1,104 @@
+import { readEnvConfigLayer } from "./env-layer.js";
+import { appConfigSchema, } from "./schema.js";
+/**
+ * Resolution order for app configuration, lowest opinion first.
+ *
+ * `legacy` is where the bespoke `configure*` / `set*` setters this schema
+ * replaces write their values, so a deprecated call still works and still has
+ * a stated position rather than whichever `if` happens to run first.
+ */
+const LAYER_ORDER = ["env", "legacy", "app"];
+// Same reason the provider registries do this: core can be loaded more than
+// once in a dev server or a dual-format build, and a config set by a plugin
+// has to be visible to a reader that resolved a different copy of the module.
+const globals = globalThis;
+const state = (globals.__agentNativeAppConfig ??= {
+    layers: {},
+});
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+/**
+ * Merges `override` onto `base`, recursing into domain subobjects so two
+ * layers can each set a different field of the same domain. Functions, arrays,
+ * and scalars replace rather than merge.
+ */
+function mergeLayers(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined)
+            continue;
+        const existing = result[key];
+        result[key] =
+            isPlainObject(existing) && isPlainObject(value)
+                ? mergeLayers(existing, value)
+                : value;
+    }
+    return result;
+}
+function resolve(envLayer) {
+    state.layers.env = envLayer;
+    let merged = {};
+    for (const layer of LAYER_ORDER) {
+        const value = state.layers[layer];
+        if (value)
+            merged = mergeLayers(merged, value);
+    }
+    return appConfigSchema.parse(merged);
+}
+/**
+ * Writes one layer of the ladder. Framework-internal: the deprecated setters
+ * use it to keep working without reintroducing a second namespace.
+ */
+export function setAppConfigLayer(layer, config) {
+    const existing = state.layers[layer];
+    const next = existing
+        ? mergeLayers(existing, config)
+        : config;
+    // Validate where the value is set, so a bad value names the call site that
+    // set it instead of whichever unrelated read happened to run first.
+    appConfigSchema.parse(next);
+    state.layers[layer] = next;
+    state.resolved = undefined;
+}
+/**
+ * Sets this app's server configuration.
+ *
+ * Call it from a server plugin. Values given here beat any environment
+ * variable aliased to the same field. Calling it more than once merges, so an
+ * app can split its configuration by domain across plugin files.
+ */
+export function defineAppConfig(config) {
+    setAppConfigLayer("app", config);
+}
+/**
+ * The resolved configuration, with declared defaults applied.
+ *
+ * The parsed result is cached, but the env layer is rebuilt each call and the
+ * cache is dropped when it differs. Re-reading a handful of declared keys is
+ * cheap next to re-parsing the schema, and caching the env read outright would
+ * mean whichever code path ran first froze the configuration for the process —
+ * a stale value nobody can see, which is the failure this module exists to
+ * remove.
+ */
+export function getAppConfig() {
+    const envLayer = readEnvConfigLayer(appConfigSchema, process.env);
+    const signature = JSON.stringify(envLayer);
+    if (state.resolved && state.envSignature === signature)
+        return state.resolved;
+    state.envSignature = signature;
+    return (state.resolved = resolve(envLayer));
+}
+/**
+ * Drops every layer and the resolved cache.
+ *
+ * The resolved object is cached on first read, so a test that mutates
+ * `process.env` between cases has to call this to be seen.
+ */
+export function resetAppConfigForTests() {
+    state.layers = {};
+    state.resolved = undefined;
+    state.envSignature = undefined;
+}