From 4fbd683819837af26c5ff4a62fd3843c2b7fa57d Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Wed, 29 Apr 2026 09:28:09 +0100
Subject: [PATCH] test: clarify manifest catalog alias planning

---
 docs/plugins/manifest.md                   |  2 ++
 src/model-catalog/manifest-planner.test.ts | 37 ++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
index 97a6429f534..579202c314f 100644
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -754,6 +754,8 @@ Top-level fields:
 Alias targets must be top-level providers owned by the same plugin. When a
 provider-filtered list uses an alias, OpenClaw can read the owning manifest and
 apply alias API/base URL overrides without loading provider runtime.
+Aliases do not expand unfiltered catalog listings; broad lists emit the owning
+canonical provider rows only.
 
 `suppressions` replaces the old provider runtime `suppressBuiltInModel` hook.
 Suppression entries are honored only when the provider is owned by the plugin or
diff --git a/src/model-catalog/manifest-planner.test.ts b/src/model-catalog/manifest-planner.test.ts
index 40bfd5ab858..55f03aa3b90 100644
--- a/src/model-catalog/manifest-planner.test.ts
+++ b/src/model-catalog/manifest-planner.test.ts
@@ -143,6 +143,43 @@ describe("manifest model catalog planner", () => {
     ]);
   });
 
+  it("keeps alias provider rows out of unfiltered broad planning", () => {
+    const plan = planManifestModelCatalogRows({
+      registry: {
+        plugins: [
+          {
+            id: "openai",
+            providers: ["openai"],
+            modelCatalog: {
+              aliases: {
+                "azure-openai-responses": {
+                  provider: "openai",
+                  api: "azure-openai-responses",
+                  baseUrl: "https://example.openai.azure.com/openai/v1",
+                },
+              },
+              providers: {
+                openai: {
+                  api: "openai-responses",
+                  baseUrl: "https://api.openai.com/v1",
+                  models: [{ id: "gpt-5.4", name: "GPT-5.4" }],
+                },
+              },
+            },
+          },
+        ],
+      },
+    });
+
+    expect(plan.entries.map((entry) => entry.provider)).toEqual(["openai"]);
+    expect(plan.rows.map((row) => row.ref)).toEqual(["openai/gpt-5.4"]);
+    expect(plan.rows).not.toContainEqual(
+      expect.objectContaining({
+        provider: "azure-openai-responses",
+      }),
+    );
+  });
+
   it("reports duplicate provider/model keys and excludes conflicted rows", () => {
     const plan = planManifestModelCatalogRows({
       registry: {