@@ -0,0 +1,20 @@
+---
+'@objectstack/cloud-connection': patch
+---
+
+feat(cloud-connection)!: the marketplace catalog list filters by business function, industry, solution type and maturity on the server, and the `?category=` filter is retired
+
+Clause-②: no (narrowing) — the facets are declared by the published `MarketplaceSearchRequestSchema` (`businessFunctions`, `industries`, `solutionTypes`, `maturity`), so implementing them widens no contract; refusing the retired `?category=` filter, and a facet the catalog cannot answer, narrows what the proxy honours. No export, type or error code of the package is added.
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no export or type of the package changes: the catalog list door reads query-string names the spec already declares and refuses one the spec already retired, with the spec's own prescription. Nothing at rest records a catalog query, so there is nothing for a migration to rewrite and no tombstone. -->
+
+**The facet filters.** `GET /api/v1/marketplace/packages` reads `businessFunctions`, `industries` and `solutionTypes`, each one comma-separated value (`?businessFunctions=sales,marketing`), and `maturity`, one value. Values inside one facet are OR-ed, facets are AND-ed with each other, with `maturity` and with `q`, and `limit` / `offset` page the filtered set, so `total` counts every matching listing. A listing that declares no solution type is the spec's default `app`, and one that declares no maturity is `stable`. On the public snapshot path (`OS_MARKETPLACE_PUBLIC_BASE_URL`) the proxy filters and pages the snapshot itself; on the cloud path it forwards the query string to the cloud unchanged, as before.
+
+**BREAKING** accept-set narrowing at the catalog list (`@objectstack/cloud-connection`).
+
+- **Before.** `?category=crm` filtered the public snapshot by the listing's retired `category` column.
+- **Now.** `?category=` is refused with `400` and the spec's retirement prescription for `MarketplaceSearchRequest.category` (`retiredCategoryGuidance`, the text a parse of `MarketplaceSearchRequestSchema` gives the same key), on the snapshot and the cloud path alike, before either is asked. A facet value the spec does not declare (`?businessFunctions=crm`), a facet supplied twice (`?industries=retail&industries=logistics`) and a facet naming no value (`?solutionTypes=`) are refused with `400` and `{ "success": false, "error": { "code": "VALIDATION_ERROR", "message" } }` before the snapshot or the cloud is asked; the message names the parameter and the values it takes.
+- **Who moves.** Nothing in the workspace sends `?category=` or a facet today; the Console filters the loaded catalog itself. A script still sending `?category=` gets the 400 instead of a filtered list.
+
+**The remedy.** Replace `?category=X` with the facet that says what you mean (`?businessFunctions=`, `?industries=`, `?solutionTypes=`), and send several values of one facet as one comma-separated value.
@@ -6,9 +6,17 @@
  * requests pass through (`next()`) so a host-supplied install route (mounted
  * via the createObjectOSStack `extraPlugins` seam) can claim them — instead of
  * the old 405 "install via cloud" dead-end (framework#1548).
+ *
+ * The catalog list door (`GET /api/v1/marketplace/packages`) filters by the
+ * spec's taxonomy facets on the server — `businessFunctions`, `industries`,
+ * `solutionTypes` (each one comma-separated value) and `maturity` — OR inside a
+ * facet, AND across, and pages the filtered set. The retired `?category=`
+ * filter is refused with the spec's prescription, and so is a facet the
+ * catalog cannot answer, before either path (public snapshot or cloud) is asked.
  */
 
-import { describe, it, expect } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { retiredCategoryGuidance } from '@objectstack/spec/marketplace';
 import { MarketplaceProxyPlugin } from './marketplace-proxy-plugin.js';
 
 /** Drive the plugin's kernel:ready wiring and capture the registered handler. */
@@ -78,3 +86,180 @@ describe('MarketplaceProxyPlugin — browse-only (no install dead-end)', () => {
         expect(result.__body?.error?.code).toBe('MARKETPLACE_UNAVAILABLE');
     });
 });
+
+// ── The catalog list door: facet filters on the server ──────────────────────
+
+const PUBLIC_BASE = 'https://public.test';
+const CLOUD = 'http://cloud.test';
+const LIST = '/api/v1/marketplace/packages';
+
+const row = (id: string, extra: Record<string, unknown> = {}) => ({
+    id,
+    manifest_id: `com.test.${id}`,
+    display_name: id.toUpperCase(),
+    latest_version: null,
+    ...extra,
+});
+
+/** A catalog snapshot: three taxonomy rows, one row from before the taxonomy. */
+const ROWS = [
+    row('crm', {
+        business_functions: ['sales', 'marketing'], industries: ['retail'],
+        solution_type: 'app', maturity: 'stable', category: 'crm',
+    }),
+    row('helpdesk', {
+        business_functions: ['customer_service'], industries: ['retail', 'logistics'],
+        solution_type: 'template', maturity: 'beta', category: 'crm',
+    }),
+    row('ledger', {
+        business_functions: ['finance', 'sales'], industries: [],
+        solution_type: 'connector', category: 'finance',
+    }),
+    row('legacy', { category: 'crm' }),
+];
+
+let fetchCalls: string[];
+
+beforeEach(() => {
+    fetchCalls = [];
+    vi.stubGlobal('fetch', vi.fn(async (input: any) => {
+        const url = String(input);
+        fetchCalls.push(url);
+        if (url === `${PUBLIC_BASE}/packages.json`) {
+            return new Response(JSON.stringify({
+                success: true,
+                data: { items: ROWS, total: ROWS.length, limit: 100, offset: 0 },
+            }), { status: 200, headers: { 'content-type': 'application/json' } });
+        }
+        if (url.startsWith(CLOUD)) {
+            return new Response(JSON.stringify({ success: true, data: { items: [], total: 0 } }), {
+                status: 200, headers: { 'content-type': 'application/json' },
+            });
+        }
+        return new Response('not found', { status: 404 });
+    }));
+});
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+async function list(query: string, opts: { publicBase?: string } = { publicBase: PUBLIC_BASE }) {
+    const plugin = new MarketplaceProxyPlugin({
+        controlPlaneUrl: CLOUD,
+        cacheDisabled: true,
+        publicMarketplaceBaseUrl: opts.publicBase ?? '',
+    });
+    const handler = await captureHandler(plugin);
+    return handler(fakeCtx('GET', `${LIST}${query}`), async () => 'NEXT');
+}
+
+async function listIds(query: string): Promise<{ ids: string[]; total: number; limit: number; offset: number }> {
+    const res: Response = await list(query);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    return {
+        ids: body.data.items.map((r: any) => r.id),
+        total: body.data.total,
+        limit: body.data.limit,
+        offset: body.data.offset,
+    };
+}
+
+describe('catalog list — facet filters on the public snapshot', () => {
+    it('ORs the values inside one facet', async () => {
+        const { ids, total } = await listIds('?businessFunctions=marketing,finance');
+        expect(ids).toEqual(['crm', 'ledger']);
+        expect(total).toBe(2);
+    });
+
+    it('ANDs across facets', async () => {
+        const { ids } = await listIds('?businessFunctions=sales,customer_service&industries=logistics');
+        expect(ids).toEqual(['helpdesk']);
+    });
+
+    it('reads a row with no solution type as the spec default (app) and no maturity as stable', async () => {
+        expect((await listIds('?solutionTypes=app')).ids).toEqual(['crm', 'legacy']);
+        expect((await listIds('?solutionTypes=template,connector')).ids).toEqual(['helpdesk', 'ledger']);
+        expect((await listIds('?maturity=beta')).ids).toEqual(['helpdesk']);
+        expect((await listIds('?maturity=stable')).ids).toEqual(['crm', 'ledger', 'legacy']);
+    });
+
+    it('a row without the taxonomy columns passes no business-function or industry filter', async () => {
+        expect((await listIds('?businessFunctions=sales')).ids).toEqual(['crm', 'ledger']);
+        expect((await listIds('?industries=retail')).ids).toEqual(['crm', 'helpdesk']);
+    });
+
+    it('folds repeats and trims values', async () => {
+        expect((await listIds('?businessFunctions=%20sales%20,sales,')).ids).toEqual(['crm', 'ledger']);
+    });
+
+    it('combines with q and pages the filtered set on the server', async () => {
+        const page = await listIds('?businessFunctions=sales,customer_service,finance&limit=2&offset=1');
+        expect(page).toEqual({ ids: ['helpdesk', 'ledger'], total: 3, limit: 2, offset: 1 });
+        expect((await listIds('?q=help&industries=retail')).ids).toEqual(['helpdesk']);
+    });
+});
+
+describe('catalog list — the retired ?category= filter', () => {
+    it('is refused with the spec prescription, before either path is asked', async () => {
+        const res: any = await list('?category=crm');
+        expect(res.__status).toBe(400);
+        expect(res.__body?.success).toBe(false);
+        expect(res.__body?.error?.code).toBe('VALIDATION_ERROR');
+        expect(res.__body?.error?.message).toContain(retiredCategoryGuidance('MarketplaceSearchRequest.category'));
+        expect(fetchCalls).toEqual([]);
+    });
+
+    it('is refused beside a filter the door reads, and on the cloud-only configuration', async () => {
+        const beside: any = await list('?category=finance&solutionTypes=app,template');
+        expect(beside.__status).toBe(400);
+        expect(beside.__body?.error?.code).toBe('VALIDATION_ERROR');
+        const cloudOnly: any = await list('?category=', { publicBase: '' });
+        expect(cloudOnly.__status).toBe(400);
+        expect(cloudOnly.__body?.error?.code).toBe('VALIDATION_ERROR');
+        expect(fetchCalls).toEqual([]);
+    });
+});
+
+describe('catalog list — refused facets', () => {
+    const refusal = async (query: string, opts?: { publicBase?: string }) => {
+        const res: any = await list(query, opts);
+        expect(res.__status).toBe(400);
+        expect(res.__body?.success).toBe(false);
+        expect(res.__body?.error?.code).toBe('VALIDATION_ERROR');
+        return String(res.__body?.error?.message);
+    };
+
+    it('refuses a value the spec does not declare for the facet, naming it', async () => {
+        expect(await refusal('?businessFunctions=sales,crm')).toContain('"crm"');
+        await refusal('?industries=Retail');
+        await refusal('?solutionTypes=theme');
+        await refusal('?maturity=preview');
+        expect(fetchCalls).toEqual([]);
+    });
+
+    it('refuses a facet supplied twice instead of choosing one occurrence', async () => {
+        expect(await refusal('?businessFunctions=sales&businessFunctions=marketing')).toContain('2 times');
+        await refusal('?maturity=beta&maturity=stable');
+    });
+
+    it('refuses a facet that names no value', async () => {
+        await refusal('?industries=');
+        await refusal('?solutionTypes=,');
+    });
+
+    it('refuses the same way when only the cloud path is configured', async () => {
+        await refusal('?businessFunctions=crm', { publicBase: '' });
+        expect(fetchCalls).toEqual([]);
+    });
+});
+
+describe('catalog list — cloud path', () => {
+    it('forwards the facet query to the cloud verbatim', async () => {
+        const query = '?businessFunctions=sales,finance&solutionTypes=template&maturity=beta&limit=20';
+        const res: Response = await list(query, { publicBase: '' });
+        expect(res.status).toBe(200);
+        expect(fetchCalls).toEqual([`${CLOUD}${LIST}${query}`]);
+    });
+});