@adobe/aio-commerce-lib-app 2.0.0-beta-20260820174436 → 2.0.0

package/CHANGELOG.md

@@ -1,11 +1,11 @@
 # @adobe/aio-commerce-lib-app
 
-## 2.0.0-beta-20260820174436
+## 2.0.0
 
 ### Major Changes
 
 - [#637](https://github.com/adobe/aio-commerce-sdk/pull/637) [`9d9888f`](https://github.com/adobe/aio-commerce-sdk/commit/9d9888f95b2cf54d76e33ab75a4599d906f438c4) Thanks [@mariam21arauj](https://github.com/mariam21arauj)! - Remove the deprecated `PUT /config` action endpoint. It overwrote every value for a scope and could not express partial updates or unset a key, which caused data loss when only a subset of keys was meant to change.
-  
+
   **Migration:** Switch calls from `PUT /config` to `PATCH /config`. The request shape is unchanged (`{ scopeId, config: [{ name, value }] }`), but send only the entries you want to change; `PATCH` leaves unmentioned keys untouched and unsets a key when its value is `null`.
 
 ### Minor Changes
@@ -14,6 +14,8 @@
 
 - [#627](https://github.com/adobe/aio-commerce-sdk/pull/627) [`e5cbdf1`](https://github.com/adobe/aio-commerce-sdk/commit/e5cbdf14f5bda56430eeeaf495889b8a1a514fe3) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Apply webhook configuration changes during upgrades when fields, conditions, headers, or other mutable settings change without changing webhook identity.
 
+- [#659](https://github.com/adobe/aio-commerce-sdk/pull/659) [`a1a7ee2`](https://github.com/adobe/aio-commerce-sdk/commit/a1a7ee273a4a0d81e3ed18e3855f1395f7b69e66) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Reconcile custom installation steps during app upgrades, so previously installed steps are not re-run and removed steps are not uninstalled until the app itself is fully uninstalled.
+
 - [#634](https://github.com/adobe/aio-commerce-sdk/pull/634) [`f8f13c1`](https://github.com/adobe/aio-commerce-sdk/commit/f8f13c139d449e7fd96afceddeed33ad103cae89) Thanks [@vinayrao2000](https://github.com/vinayrao2000)! - Reconcile configuration changes to existing Admin UI components during an upgrade. The Admin UI step now detects when a component present in both the installed and target versions has a changed configuration (ACL, labels, descriptions, notifications) and refreshes the extension to apply it, instead of leaving the change unapplied.
 
 - [#625](https://github.com/adobe/aio-commerce-sdk/pull/625) [`e0852d1`](https://github.com/adobe/aio-commerce-sdk/commit/e0852d11e1b4f7c23a0c0dfd1d41acf984aeba7a) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Reconcile Commerce event subscription configuration changes during an app upgrade. When an event that exists in both the installed baseline and the target config changes its fields, rules, priority or HIPAA flag, the upgrade now updates the live subscription instead of leaving it stale.
@@ -26,12 +28,20 @@
 
 - [#621](https://github.com/adobe/aio-commerce-sdk/pull/621) [`03c4cc3`](https://github.com/adobe/aio-commerce-sdk/commit/03c4cc3958ccd9425f55c891b352d9804a466269) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Add upgrade planning support for webhook additions and removals: the webhooks step now diffs the baseline snapshot against the target configuration to add newly configured webhooks and remove ones dropped from it.
 
+- [#650](https://github.com/adobe/aio-commerce-sdk/pull/650) [`f3ea3a6`](https://github.com/adobe/aio-commerce-sdk/commit/f3ea3a64ac59c978f28865274fa282ec991ea529) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Fix uninstallation failing for apps with a `dynamicList` Business Configuration field, caused by revalidating the recorded installation snapshot against a schema that required functions a JSON-serialized snapshot can never have. Uninstallation now validates the recorded config with `validateRecordedCommerceAppConfig`, which accepts a `dynamicList` field without `options`/`default`.
+
 - [#614](https://github.com/adobe/aio-commerce-sdk/pull/614) [`01d5013`](https://github.com/adobe/aio-commerce-sdk/commit/01d5013015cac472220b6c69dcb25f101a682c33) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Use `isConfigured` when defining lifecycle steps to identify whether their domain is present in app configuration. The deprecated `when` predicate remains supported for compatibility.
 
+- [#653](https://github.com/adobe/aio-commerce-sdk/pull/653) [`c04983d`](https://github.com/adobe/aio-commerce-sdk/commit/c04983dfe04926094ab810c070598d5609004a61) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Add support for declaring custom ACL resources under `adminUi.acl` (flat leaves or one-level groups) that are injected into the Commerce User Roles tree for app-checked permissions. An app declaring only ACL resources does not register a `commerce/backend-ui/2` extension point (in `app.config.yaml`, `install.yaml`, or generated ext.config), since ACL resources reach Commerce through the app-config payload.
+
 ### Patch Changes
 
+- [#653](https://github.com/adobe/aio-commerce-sdk/pull/653) [`c04983d`](https://github.com/adobe/aio-commerce-sdk/commit/c04983dfe04926094ab810c070598d5609004a61) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Reject Admin UI ids that would map to the same Commerce permission. Conflicting grid column, mass action, order view button, or custom ACL resource ids now fail config validation instead of silently overwriting one another.
+
 - [#636](https://github.com/adobe/aio-commerce-sdk/pull/636) [`186d245`](https://github.com/adobe/aio-commerce-sdk/commit/186d245015bd405ce5f1ea45d796069ab2f03fac) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Fix the Admin UI SDK installation step timing out by raising the Commerce HTTP client timeout to 2 minutes, matching the events and webhooks installation steps. Apply the same timeout to the Commerce scope sync endpoint.
 
+- [#680](https://github.com/adobe/aio-commerce-sdk/pull/680) [`1612b38`](https://github.com/adobe/aio-commerce-sdk/commit/1612b38516e734155c50f545b8f41120f55d5351) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Ensure required Admin UI web source support files are present, including an environment-aware Babel configuration that produces compatible production JSX.
+
 - [#639](https://github.com/adobe/aio-commerce-sdk/pull/639) [`74b9a3b`](https://github.com/adobe/aio-commerce-sdk/commit/74b9a3b6274215ba2e97fa56a94e737c62e2b8bb) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Ensure CLI commands find the project root before generating files or updating project configuration.
 
 - [#642](https://github.com/adobe/aio-commerce-sdk/pull/642) [`79dcda0`](https://github.com/adobe/aio-commerce-sdk/commit/79dcda035d322d47d2e19566ae4a20fd6124682b) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Install Node.js type definitions when initializing TypeScript projects.
@@ -39,9 +49,25 @@
 - [#627](https://github.com/adobe/aio-commerce-sdk/pull/627) [`e5cbdf1`](https://github.com/adobe/aio-commerce-sdk/commit/e5cbdf14f5bda56430eeeaf495889b8a1a514fe3) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Reject webhook configurations with unsupported webhook types or HTTP methods.
 
 - [#643](https://github.com/adobe/aio-commerce-sdk/pull/643) [`d13ca97`](https://github.com/adobe/aio-commerce-sdk/commit/d13ca977cbe5c683e0515c24350863a46dc52792) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Prune app-owned Commerce webhooks that are absent from the target configuration during upgrades.
-- Updated dependencies [[`f012ae0`](https://github.com/adobe/aio-commerce-sdk/commit/f012ae0d8eaac5cac314a62de3902fca842bd936), [`e0852d1`](https://github.com/adobe/aio-commerce-sdk/commit/e0852d11e1b4f7c23a0c0dfd1d41acf984aeba7a)]:
-  - @adobe/aio-commerce-lib-admin-ui@1.1.0-beta-20260820174436
-  - @adobe/aio-commerce-lib-events@1.4.0-beta-20260820174436
+
+- [#672](https://github.com/adobe/aio-commerce-sdk/pull/672) [`4bed4e3`](https://github.com/adobe/aio-commerce-sdk/commit/4bed4e306f3a889fd1ea81d3f8d3f11609fd2a58) Thanks [@vinayrao2000](https://github.com/vinayrao2000)! - Fix upgrades failing with a 404 "no such event metadata" error when a duplicate event provider exists in the org.
+- Updated dependencies [[`f012ae0`](https://github.com/adobe/aio-commerce-sdk/commit/f012ae0d8eaac5cac314a62de3902fca842bd936), [`c04983d`](https://github.com/adobe/aio-commerce-sdk/commit/c04983dfe04926094ab810c070598d5609004a61), [`e0852d1`](https://github.com/adobe/aio-commerce-sdk/commit/e0852d11e1b4f7c23a0c0dfd1d41acf984aeba7a), [`c04983d`](https://github.com/adobe/aio-commerce-sdk/commit/c04983dfe04926094ab810c070598d5609004a61), [`1837df1`](https://github.com/adobe/aio-commerce-sdk/commit/1837df107bd2b8d2211f77438a07b6e7ee0af03e), [`f3ea3a6`](https://github.com/adobe/aio-commerce-sdk/commit/f3ea3a64ac59c978f28865274fa282ec991ea529)]:
+  - @adobe/aio-commerce-lib-admin-ui@1.1.0
+  - @adobe/aio-commerce-lib-events@1.4.0
+  - @adobe/aio-commerce-lib-api@1.4.0
+  - @adobe/aio-commerce-lib-config@1.8.0
+  - @adobe/aio-commerce-lib-webhooks@1.2.2
+
+## 1.11.0
+
+### Minor Changes
+
+- [#650](https://github.com/adobe/aio-commerce-sdk/pull/650) [`f3ea3a6`](https://github.com/adobe/aio-commerce-sdk/commit/f3ea3a64ac59c978f28865274fa282ec991ea529) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Fix uninstallation failing for apps with a `dynamicList` Business Configuration field, caused by revalidating the recorded installation snapshot against a schema that required functions a JSON-serialized snapshot can never have. Uninstallation now validates the recorded config with `validateRecordedCommerceAppConfig`, which accepts a `dynamicList` field without `options`/`default`.
+
+### Patch Changes
+
+- Updated dependencies [[`f3ea3a6`](https://github.com/adobe/aio-commerce-sdk/commit/f3ea3a64ac59c978f28865274fa282ec991ea529)]:
+  - @adobe/aio-commerce-lib-config@1.7.0
 
 ## 1.10.1
 

package/dist/cjs/actions/app-config/index.cjs

@@ -15,7 +15,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_rolldown_runtime = require('../../rolldown-runtime-CDQd2xEI.cjs');
 const require_environment = require('../../environment-B6533pAY.cjs');
-const require_validate = require('../../validate-Dff0nrqM.cjs');
+const require_validate = require('../../validate-CwWYtRsS.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
 let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
 let valibot = require("valibot");
@@ -29,7 +29,7 @@ let crypto = require("crypto");
 * Loads the committed OpenAPI spec via dynamic import so it
 * lands in its own chunk and is not parsed on every cold start.
 */
-const importOpenApi = () => Promise.resolve().then(() => require("../../openapi-DVJUTOXY.cjs"));
+const importOpenApi = () => Promise.resolve().then(() => require("../../openapi-CAXgKam0.cjs"));
 /** Matches component schema `$ref` strings, capturing the schema name. */
 const SCHEMA_REF_PATTERN = /"#\/components\/schemas\/(\w+)"/g;
 /**
@@ -80,7 +80,7 @@ function pruneUnusedTags(spec) {
 * @param domains - The active config domains.
 */
 function getOpenApiCacheKey(domains) {
-	const input = `2.0.0-beta-20260820174436:${[...domains].sort().join(",")}:3.0.0`;
+	const input = `2.0.0:${[...domains].sort().join(",")}:3.0.0`;
 	return (0, crypto.createHash)("sha256").update(input).digest("hex").slice(0, 8);
 }
 /** Returns the server URL to be set in the OpenAPI spec, based on the current namespace. */

package/dist/cjs/actions/app-config/index.d.cts

@@ -13,7 +13,7 @@
  */
 
 import "../../index-DWEigxhy.cjs";
-import { n as CommerceAppConfig } from "../../app-Cf3EmtUh.cjs";
+import { n as CommerceAppConfig } from "../../app-DwSqUkJA.cjs";
 import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
 //#region source/actions/app-config/router.d.ts
 /** The arguments required to create the runtime action for the app-config action. */
@@ -26,6 +26,5 @@ type RuntimeActionFactoryArgs = {
  * Factory to create the route handler for the `app-config` action.
  * @param args - The arguments required to create the runtime action.
  */
-declare const appConfigRuntimeAction: (args: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
-//#endregion
-export { appConfigRuntimeAction };
+export declare const appConfigRuntimeAction: (args: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion

package/dist/cjs/actions/association/index.d.cts

@@ -22,6 +22,5 @@ import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
  * and `DELETE /` clears it on unassociation. Runtime actions consume the data
  * via `getCommerceInstance` / `getCommerceClient` from the root entrypoint.
  */
-declare const associationRuntimeAction: () => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
-//#endregion
-export { associationRuntimeAction };
+export declare const associationRuntimeAction: () => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion

package/dist/cjs/actions/config/index.d.cts

@@ -26,6 +26,5 @@ type ConfigActionFactoryArgs = {
  * Factory to create the route handler for the `config` action.
  * @param args - The arguments required to create the runtime action.
  */
-declare const configRuntimeAction: (args: ConfigActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
-//#endregion
-export { configRuntimeAction };
+export declare const configRuntimeAction: (args: ConfigActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion

package/dist/cjs/actions/installation/index.cjs

@@ -16,9 +16,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_rolldown_runtime = require('../../rolldown-runtime-CDQd2xEI.cjs');
 const require_repository = require('../../repository-CbceYZqc.cjs');
 const require_schemas = require('../../schemas-3e49M8zz.cjs');
-const require_validate = require('../../validate-Dff0nrqM.cjs');
-const require_common = require('../../common-B70f39vI.cjs');
-const require_management = require('../../management-BhMdRr8i.cjs');
+const require_validate = require('../../validate-CwWYtRsS.cjs');
+const require_common = require('../../common-VSsQEHDv.cjs');
+const require_management = require('../../management-Bki3hlxL.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
 let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot, 1);
@@ -371,11 +371,16 @@ async function startUninstallation({ body, logger, rawParams }) {
 		return (0, _adobe_aio_commerce_lib_core_responses.conflict)("Uninstallation is already in progress. Wait for it to complete.");
 	}
 	const { baselineProvider, stateStore } = await require_common.createLifecyclePersistence();
-	const baselineAppConfig = (await require_common.getCurrentLifecycleBaseline(stateStore, baselineProvider))?.config;
+	const installationSnapshot = await require_common.getCurrentLifecycleBaseline(stateStore, baselineProvider);
+	const baselineAppConfig = installationSnapshot?.config;
 	const uninstallConfig = baselineAppConfig ?? rawParams.appConfig;
 	if (!uninstallConfig) return (0, _adobe_aio_commerce_lib_core_responses.internalServerError)("Cannot determine what to uninstall: no recorded lifecycle baseline and no app config was provided.");
 	logger.debug(baselineAppConfig ? "Sourcing uninstallation from recorded lifecycle baseline" : "No recorded lifecycle baseline found; falling back to request config");
-	const initialState = require_management.createInitialUninstallationState({ config: require_validate.validateCommerceAppConfig(uninstallConfig) });
+	const executedCustomInstallationSteps = require_common.getExecutedCustomInstallationSteps(installationSnapshot?.data);
+	const initialState = require_management.createInitialUninstallationState({
+		config: require_validate.validateRecordedCommerceAppConfig(uninstallConfig),
+		executedCustomInstallationSteps
+	});
 	logger.debug(`Created initial uninstall state: ${initialState.id}`);
 	await store.put(require_common.getStorageKey(), initialState);
 	const workflowParams = require_common.buildWorkflowParams(body, rawParams);
@@ -387,6 +392,7 @@ async function startUninstallation({ body, logger, rawParams }) {
 			__ow_method: "post",
 			__ow_path: "/uninstallation/execution",
 			appConfig: uninstallConfig,
+			executedCustomInstallationSteps,
 			initialState
 		},
 		result: false
@@ -400,16 +406,17 @@ async function startUninstallation({ body, logger, rawParams }) {
 }
 /** Runs the uninstallation workflow and clears lifecycle state on success. */
 async function executeUninstallation({ logger, params }) {
-	const { initialState, appConfig: rawAppConfig, appData, AIO_COMMERCE_API_BASE_URL } = params;
+	const { initialState, appConfig: rawAppConfig, appData, AIO_COMMERCE_API_BASE_URL, executedCustomInstallationSteps = [] } = params;
 	if (!initialState) return (0, _adobe_aio_commerce_lib_core_responses.badRequest)("initialState is required for execution");
 	if (!rawAppConfig) return (0, _adobe_aio_commerce_lib_core_responses.badRequest)("appConfig is required for execution");
-	const appConfig = require_validate.validateCommerceAppConfig(rawAppConfig);
+	const appConfig = require_validate.validateRecordedCommerceAppConfig(rawAppConfig);
 	const store = await require_common.createUninstallationStore();
 	const hooks = require_common.createInstallationHooks(store, (msg) => logger.debug(msg));
 	const installationContext = require_common.buildLifecycleContext(params, appConfig, logger);
 	logger.debug(`Executing uninstallation ${initialState.id} for app "${appData.projectName}" (workspace: "${appData.workspaceName}", commerce: "${AIO_COMMERCE_API_BASE_URL}")`);
 	const result = await require_management.runUninstallation({
 		config: appConfig,
+		executedCustomInstallationSteps,
 		hooks,
 		initialState,
 		installationContext

package/dist/cjs/actions/installation/index.d.cts

@@ -13,8 +13,8 @@
  */
 
 import "../../index-DWEigxhy.cjs";
-import { n as CommerceAppConfig, r as CommerceAppConfigOutputModel } from "../../app-Cf3EmtUh.cjs";
-import { J as LifecycleContext } from "../../index-CkwCGvut.cjs";
+import { n as CommerceAppConfig, r as CommerceAppConfigOutputModel } from "../../app-DwSqUkJA.cjs";
+import { J as LifecycleContext } from "../../index-C7dqTDHu.cjs";
 import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
 import "@adobe/aio-commerce-lib-core/responses";
 //#region source/actions/installation/common.d.ts
@@ -31,11 +31,11 @@ type RuntimeActionFactoryArgs = {
  * Defines a type-safe custom installation scripts loader.
  * @param loader - The custom scripts loader implementation.
  */
-declare function defineCustomScriptsLoader(loader: CustomScriptsLoader): CustomScriptsLoader;
+export declare function defineCustomScriptsLoader(loader: CustomScriptsLoader): CustomScriptsLoader;
 /**
  * Factory to create the route handler for the `installation` action.
  * @param args - The arguments required to create the runtime action.
  */
-declare const installationRuntimeAction: (args: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+export declare const installationRuntimeAction: (args: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
 //#endregion
-export { type CustomScriptsLoader, defineCustomScriptsLoader, installationRuntimeAction };
+export type { CustomScriptsLoader };

package/dist/cjs/actions/scope-tree/index.d.cts

@@ -14,6 +14,5 @@
 
 //#region source/actions/scope-tree/index.d.ts
 /** The handler method for the `scope-tree` action. */
-declare const scopeTreeRuntimeAction: (args: import("@adobe/aio-commerce-lib-core/params").RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
-//#endregion
-export { scopeTreeRuntimeAction };
+export declare const scopeTreeRuntimeAction: (args: import("@adobe/aio-commerce-lib-core/params").RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion

package/dist/cjs/{app-Cf3EmtUh.d.cts → app-DwSqUkJA.d.cts}

@@ -17,6 +17,41 @@ import * as v from "valibot";
 /** The individual validatable domains of the app config. */
 declare const CommerceAppConfigSchemas: {
   readonly adminUi: v.ObjectSchema<{
+    readonly acl: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+      readonly children: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.RegexAction<string, "ACL resource ID may contain only lowercase letters, digits, and \"_\"">]>;
+        readonly label: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.MinLengthAction<string, 3, "acl resource label must be at least 3 characters">, v.MaxLengthAction<string, 50, "acl resource label must be at most 50 characters">]>;
+      }, undefined>, undefined>, v.MinLengthAction<{
+        id: string;
+        label: string;
+      }[], 1, "An ACL resource group must contain at least one child">, v.CheckAction<{
+        id: string;
+        label: string;
+      }[], "Child ACL resource ids must be unique within a group.">]>, undefined>;
+      readonly id: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.RegexAction<string, "ACL resource ID may contain only lowercase letters, digits, and \"_\"">]>;
+      readonly label: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.MinLengthAction<string, 3, "acl resource label must be at least 3 characters">, v.MaxLengthAction<string, 50, "acl resource label must be at most 50 characters">]>;
+    }, undefined>, undefined>, v.MinLengthAction<{
+      children?: {
+        id: string;
+        label: string;
+      }[] | undefined;
+      id: string;
+      label: string;
+    }[], 1, "At least one ACL resource is required when acl is defined">, v.CheckAction<{
+      children?: {
+        id: string;
+        label: string;
+      }[] | undefined;
+      id: string;
+      label: string;
+    }[], "Top-level ACL resource ids must be unique.">, v.CheckAction<{
+      children?: {
+        id: string;
+        label: string;
+      }[] | undefined;
+      id: string;
+      label: string;
+    }[], "Custom ACL resource ids must stay unique after Commerce derivation: a top-level resource id must not equal a group's \"<group>_<child>\" combination.">]>, undefined>;
     readonly customer: v.OptionalSchema<v.ObjectSchema<{
       readonly gridColumns: v.OptionalSchema<v.ObjectSchema<{
         readonly columns: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
@@ -31,7 +66,13 @@ declare const CommerceAppConfigSchemas: {
           id: string;
           label: string;
           type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
-        }[], 1, "At least one grid column is required">]>;
+        }[], 1, "At least one grid column is required">, v.CheckAction<{
+          aclProtected?: boolean | undefined;
+          align: "left" | "right" | "center";
+          id: string;
+          label: string;
+          type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
+        }[], "Grid column ids must be unique after Commerce id sanitization.">]>;
         readonly description: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly label: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly runtimeAction: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
@@ -108,7 +149,7 @@ declare const CommerceAppConfigSchemas: {
         } | undefined;
         selectionLimit?: number | undefined;
         title?: string | undefined;
-      })[], "Mass action ids must be unique.">]>, undefined>;
+      })[], "Mass action ids must be unique after Commerce id sanitization.">]>, undefined>;
     }, undefined>, undefined>;
     readonly menu: v.OptionalSchema<v.ObjectSchema<{
       readonly aclProtected: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
@@ -133,7 +174,13 @@ declare const CommerceAppConfigSchemas: {
           id: string;
           label: string;
           type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
-        }[], 1, "At least one grid column is required">]>;
+        }[], 1, "At least one grid column is required">, v.CheckAction<{
+          aclProtected?: boolean | undefined;
+          align: "left" | "right" | "center";
+          id: string;
+          label: string;
+          type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
+        }[], "Grid column ids must be unique after Commerce id sanitization.">]>;
         readonly description: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly label: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly runtimeAction: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
@@ -210,7 +257,7 @@ declare const CommerceAppConfigSchemas: {
         } | undefined;
         selectionLimit?: number | undefined;
         title?: string | undefined;
-      })[], "Mass action ids must be unique.">]>, undefined>;
+      })[], "Mass action ids must be unique after Commerce id sanitization.">]>, undefined>;
       readonly viewButtons: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.VariantSchema<"type", [v.StrictObjectSchema<{
         readonly aclProtected: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly confirm: v.OptionalSchema<v.ObjectSchema<{
@@ -283,7 +330,7 @@ declare const CommerceAppConfigSchemas: {
         sortOrder?: number | undefined;
         timeout?: number | undefined;
         type: "worker";
-      })[], "Order view button ids must be unique.">]>, undefined>;
+      })[], "Order view button ids must be unique after Commerce id sanitization.">]>, undefined>;
     }, undefined>, undefined>;
     readonly product: v.OptionalSchema<v.ObjectSchema<{
       readonly gridColumns: v.OptionalSchema<v.ObjectSchema<{
@@ -299,7 +346,13 @@ declare const CommerceAppConfigSchemas: {
           id: string;
           label: string;
           type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
-        }[], 1, "At least one grid column is required">]>;
+        }[], 1, "At least one grid column is required">, v.CheckAction<{
+          aclProtected?: boolean | undefined;
+          align: "left" | "right" | "center";
+          id: string;
+          label: string;
+          type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
+        }[], "Grid column ids must be unique after Commerce id sanitization.">]>;
         readonly description: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly label: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly runtimeAction: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
@@ -376,7 +429,7 @@ declare const CommerceAppConfigSchemas: {
         } | undefined;
         selectionLimit?: number | undefined;
         title?: string | undefined;
-      })[], "Mass action ids must be unique.">]>, undefined>;
+      })[], "Mass action ids must be unique after Commerce id sanitization.">]>, undefined>;
     }, undefined>, undefined>;
   }, undefined>;
   readonly businessConfig: v.ObjectSchema<{
@@ -1091,7 +1144,7 @@ declare const CommerceAppConfigSchemas: {
     readonly description: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string for the ${string}`>, v.NonEmptyAction<string, `The ${string} must not be empty`>]>, v.MaxLengthAction<string, 255, "The metadata description must not be longer than 255 characters">]>;
     readonly displayName: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string for the ${string}`>, v.NonEmptyAction<string, `The ${string} must not be empty`>]>, v.MaxLengthAction<string, 50, "The application display name must not be longer than 50 characters">]>;
     readonly id: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.RegexAction<string, `Only alphanumeric characters and hyphens are allowed in string value of "${string}"${string}`>]>, v.MaxLengthAction<string, 100, "The application id must not be longer than 100 characters">]>;
-    readonly upgradeMode: v.OptionalSchema<v.PicklistSchema<["auto", "manual"], undefined>, "auto">;
+    readonly upgradeMode: v.OptionalSchema<v.PicklistSchema<["auto", "manual"], undefined>, "manual">;
     readonly version: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string for the ${string}`>, v.NonEmptyAction<string, `The ${string} must not be empty`>]>, v.RegexAction<string, "The version must follow semantic versioning (semver) format: Major.Minor.Patch (e.g., '1.0.0', '2.3.1')">]>;
   }, undefined>;
   readonly webhooks: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
@@ -1248,6 +1301,41 @@ declare function hasConfigDomain(config: AnyCommerceAppConfig, domain: CommerceA
 /** The schema used to validate the commerce app config file. */
 declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
   readonly adminUi: v.OptionalSchema<v.ObjectSchema<{
+    readonly acl: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+      readonly children: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.RegexAction<string, "ACL resource ID may contain only lowercase letters, digits, and \"_\"">]>;
+        readonly label: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.MinLengthAction<string, 3, "acl resource label must be at least 3 characters">, v.MaxLengthAction<string, 50, "acl resource label must be at most 50 characters">]>;
+      }, undefined>, undefined>, v.MinLengthAction<{
+        id: string;
+        label: string;
+      }[], 1, "An ACL resource group must contain at least one child">, v.CheckAction<{
+        id: string;
+        label: string;
+      }[], "Child ACL resource ids must be unique within a group.">]>, undefined>;
+      readonly id: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.RegexAction<string, "ACL resource ID may contain only lowercase letters, digits, and \"_\"">]>;
+      readonly label: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, v.MinLengthAction<string, 3, "acl resource label must be at least 3 characters">, v.MaxLengthAction<string, 50, "acl resource label must be at most 50 characters">]>;
+    }, undefined>, undefined>, v.MinLengthAction<{
+      children?: {
+        id: string;
+        label: string;
+      }[] | undefined;
+      id: string;
+      label: string;
+    }[], 1, "At least one ACL resource is required when acl is defined">, v.CheckAction<{
+      children?: {
+        id: string;
+        label: string;
+      }[] | undefined;
+      id: string;
+      label: string;
+    }[], "Top-level ACL resource ids must be unique.">, v.CheckAction<{
+      children?: {
+        id: string;
+        label: string;
+      }[] | undefined;
+      id: string;
+      label: string;
+    }[], "Custom ACL resource ids must stay unique after Commerce derivation: a top-level resource id must not equal a group's \"<group>_<child>\" combination.">]>, undefined>;
     readonly customer: v.OptionalSchema<v.ObjectSchema<{
       readonly gridColumns: v.OptionalSchema<v.ObjectSchema<{
         readonly columns: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
@@ -1262,7 +1350,13 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
           id: string;
           label: string;
           type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
-        }[], 1, "At least one grid column is required">]>;
+        }[], 1, "At least one grid column is required">, v.CheckAction<{
+          aclProtected?: boolean | undefined;
+          align: "left" | "right" | "center";
+          id: string;
+          label: string;
+          type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
+        }[], "Grid column ids must be unique after Commerce id sanitization.">]>;
         readonly description: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly label: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly runtimeAction: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
@@ -1339,7 +1433,7 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
         } | undefined;
         selectionLimit?: number | undefined;
         title?: string | undefined;
-      })[], "Mass action ids must be unique.">]>, undefined>;
+      })[], "Mass action ids must be unique after Commerce id sanitization.">]>, undefined>;
     }, undefined>, undefined>;
     readonly menu: v.OptionalSchema<v.ObjectSchema<{
       readonly aclProtected: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
@@ -1364,7 +1458,13 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
           id: string;
           label: string;
           type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
-        }[], 1, "At least one grid column is required">]>;
+        }[], 1, "At least one grid column is required">, v.CheckAction<{
+          aclProtected?: boolean | undefined;
+          align: "left" | "right" | "center";
+          id: string;
+          label: string;
+          type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
+        }[], "Grid column ids must be unique after Commerce id sanitization.">]>;
         readonly description: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly label: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly runtimeAction: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
@@ -1441,7 +1541,7 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
         } | undefined;
         selectionLimit?: number | undefined;
         title?: string | undefined;
-      })[], "Mass action ids must be unique.">]>, undefined>;
+      })[], "Mass action ids must be unique after Commerce id sanitization.">]>, undefined>;
       readonly viewButtons: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.VariantSchema<"type", [v.StrictObjectSchema<{
         readonly aclProtected: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly confirm: v.OptionalSchema<v.ObjectSchema<{
@@ -1514,7 +1614,7 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
         sortOrder?: number | undefined;
         timeout?: number | undefined;
         type: "worker";
-      })[], "Order view button ids must be unique.">]>, undefined>;
+      })[], "Order view button ids must be unique after Commerce id sanitization.">]>, undefined>;
     }, undefined>, undefined>;
     readonly product: v.OptionalSchema<v.ObjectSchema<{
       readonly gridColumns: v.OptionalSchema<v.ObjectSchema<{
@@ -1530,7 +1630,13 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
           id: string;
           label: string;
           type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
-        }[], 1, "At least one grid column is required">]>;
+        }[], 1, "At least one grid column is required">, v.CheckAction<{
+          aclProtected?: boolean | undefined;
+          align: "left" | "right" | "center";
+          id: string;
+          label: string;
+          type: "string" | "boolean" | "date" | "datetime" | "float" | "integer";
+        }[], "Grid column ids must be unique after Commerce id sanitization.">]>;
         readonly description: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly label: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
         readonly runtimeAction: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
@@ -1607,7 +1713,7 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
         } | undefined;
         selectionLimit?: number | undefined;
         title?: string | undefined;
-      })[], "Mass action ids must be unique.">]>, undefined>;
+      })[], "Mass action ids must be unique after Commerce id sanitization.">]>, undefined>;
     }, undefined>, undefined>;
   }, undefined>, undefined>;
   readonly businessConfig: v.OptionalSchema<v.ObjectSchema<{
@@ -1975,7 +2081,7 @@ declare const CommerceAppConfigSchema: v.LooseObjectSchema<{
     readonly description: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string for the ${string}`>, v.NonEmptyAction<string, `The ${string} must not be empty`>]>, v.MaxLengthAction<string, 255, "The metadata description must not be longer than 255 characters">]>;
     readonly displayName: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string for the ${string}`>, v.NonEmptyAction<string, `The ${string} must not be empty`>]>, v.MaxLengthAction<string, 50, "The application display name must not be longer than 50 characters">]>;
     readonly id: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.RegexAction<string, `Only alphanumeric characters and hyphens are allowed in string value of "${string}"${string}`>]>, v.MaxLengthAction<string, 100, "The application id must not be longer than 100 characters">]>;
-    readonly upgradeMode: v.OptionalSchema<v.PicklistSchema<["auto", "manual"], undefined>, "auto">;
+    readonly upgradeMode: v.OptionalSchema<v.PicklistSchema<["auto", "manual"], undefined>, "manual">;
     readonly version: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string for the ${string}`>, v.NonEmptyAction<string, `The ${string} must not be empty`>]>, v.RegexAction<string, "The version must follow semantic versioning (semver) format: Major.Minor.Patch (e.g., '1.0.0', '2.3.1')">]>;
   }, undefined>;
   readonly webhooks: v.OptionalSchema<v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{