@@ -0,0 +1,15 @@
+---
+'@objectstack/connector-openapi': minor
+---
+
+feat(connector-openapi): a declarative `openapi` instance takes `providerConfig.include`, an operation allowlist
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+A `provider: 'openapi'` connector instance can now list the operations it exposes: `providerConfig.include: string[]`. Only the listed operations become actions, so a large API (hundreds or thousands of operations) comes up as the handful of actions its flows call, without trimming the document by hand. The key has the same allowlist meaning as the `mcp` provider's `include`.
+
+- **An entry is an action key.** Write an operation's `operationId`, or, for an operation the document gives no `operationId`, its generated `method_path` key (`delete /customers/{id}` is `delete_customers_id`). An operation that has an `operationId` is named only by it. These are the same keys the actions are exposed under, so the `actionId` in a flow and the entry in `include` are spelled the same way.
+- **An unknown entry fails the boot.** An entry the document does not carry (a typo, or an operation the upstream renamed or removed) is a configuration fault at materialization: boot fails, or the entry is skipped on reload, with an error naming the entry and listing the document's keys. It is never ignored.
+- **The shape is checked before the document loads.** An `include` that is not an array of non-empty strings is refused the same way, so a malformed allowlist never exposes the whole document.
+- An instance without `include` is unchanged: every operation is an action.
@@ -118,8 +118,9 @@ Do not put a credential in `headers` or `defaultHeaders`: both are stored in met
 
 ### `provider: 'openapi'` — one action per operation
 
-Config: **`spec`** (required) and **`baseUrl`** (optional — overrides the
-document's `servers[0].url`). The `spec` takes any of three forms:
+Config: **`spec`** (required), **`baseUrl`** (optional — overrides the
+document's `servers[0].url`) and **`include`** (optional operation allowlist —
+only the listed operations become actions). The `spec` takes any of three forms:
 
 - an **inline OpenAPI 3.x document object** — no I/O at boot, the most
   deterministic form;
@@ -148,6 +149,23 @@ Each operation becomes an action keyed by its `operationId` (or a
 `method_path` slug when the document omits one) — so `getInvoice` in the
 document is `actionId: 'getInvoice'` in your flow.
 
+`include` takes those same action keys and has the same allowlist meaning as
+the `mcp` provider's `include`: list the operations the instance should expose
+and every other operation stays out — the way to bring up a large API (hundreds
+or thousands of operations) as the handful of actions your flows call. An
+operation without an `operationId` is named by its generated `method_path` key
+(`delete /customers/{id}` → `delete_customers_id`); one that has an
+`operationId` is named only by it. An entry the document does not carry — a
+typo, or an operation the upstream renamed or removed — fails the boot with an
+error naming the entry and listing the document's keys; it is never ignored.
+
+```typescript
+providerConfig: {
+  spec: './specs/crm-openapi.json',
+  include: ['listCustomers', 'getCustomer', 'delete_customers_id'],
+},
+```
+
 The document must be **OpenAPI 3.x**. A Swagger 2.0 document — or one with no
 `openapi` version field — is refused at boot with an error naming the inline
 document, URL or file it came from: convert it to OpenAPI 3.x offline and point
 
@@ -206,7 +206,7 @@ export function createOpenApiConnector(config: OpenApiConnectorConfig): OpenApiC
 
     for (const op of collectOperations(document)) {
         if (include && !include(toInfo(op))) continue;
-        const key = uniqueKey(op.operationId ?? slug(`${op.method}_${op.path}`), seenKeys);
+        const key = uniqueKey(operationActionKey(op), seenKeys);
 
         actions.push({
             key,
@@ -268,6 +268,18 @@ function collectOperations(doc: OpenApiDocument): Op[] {
     return ops;
 }
 
+/**
+ * The action key an operation generates: its `operationId`, else the
+ * `method_path` slug (`get /pets/{id}` → `get_pets_id`). The one derivation of
+ * that key — the generator keys its actions with it (before the collision
+ * suffix {@link uniqueKey} adds), and the declarative `openapi` provider's
+ * `providerConfig.include` matches its entries against it, so an allowlist
+ * entry and the action it admits can never be spelled two ways.
+ */
+export function operationActionKey(op: Pick<OperationInfo, 'operationId' | 'method' | 'path'>): string {
+    return op.operationId ?? slug(`${op.method}_${op.path}`);
+}
+
 function toInfo(op: Op): OperationInfo {
     return {
         operationId: op.operationId,
 
@@ -4,8 +4,11 @@
 // `provider: 'openapi'` connector instance from a spec document + resolved auth.
 
 import { describe, it, expect } from 'vitest';
+import { LiteKernel } from '@objectstack/core';
 import type { ConnectorProviderContext } from '@objectstack/spec/integration';
 import { isConnectorUpstreamUnavailable, RetryConfigSchema } from '@objectstack/spec/integration';
+import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/service-automation';
+import { ConnectorOpenApiPlugin } from './connector-openapi-plugin.js';
 import { createOpenApiProviderFactory, OPENAPI_PROVIDER_KEY } from './openapi-provider.js';
 
 const petstore = {
@@ -322,3 +325,143 @@ describe('openapi provider — refuses a document that is not OpenAPI 3.x', () =
         }
     });
 });
+
+// ── providerConfig.include — a declarative operation allowlist ─────────────
+//
+// The same allowlist meaning as the mcp provider's `include`: only the listed
+// operations become actions. An entry is an operation's action key — its
+// operationId, or the generated method_path key when it has none — and an
+// entry naming an operation the document does not carry is a plain (fatal)
+// configuration fault at materialization, never ignored.
+
+describe('openapi provider — providerConfig.include', () => {
+    const crm = {
+        openapi: '3.0.3',
+        info: { title: 'CRM', version: '1.0.0' },
+        servers: [{ url: 'https://crm.example.com' }],
+        paths: {
+            '/customers': {
+                get: { operationId: 'listCustomers', responses: { '200': { description: 'ok' } } },
+                post: { operationId: 'createCustomer', responses: { '201': { description: 'created' } } },
+            },
+            '/customers/{id}': {
+                // No operationId: the action key is the generated method_path slug.
+                delete: { responses: { '204': { description: 'gone' } } },
+            },
+        },
+    };
+
+    async function refusal(result: unknown): Promise<Error> {
+        const err = await Promise.resolve(result).then(
+            () => { throw new Error('expected rejection'); },
+            (e: unknown) => e,
+        );
+        expect(err).toBeInstanceOf(Error);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+        return err as Error;
+    }
+
+    it('without include, every operation is an action (control)', async () => {
+        const { def } = await createOpenApiProviderFactory()(ctx({ providerConfig: { spec: crm } }));
+        expect(def.actions?.map((a) => a.key)).toEqual(['listCustomers', 'createCustomer', 'delete_customers_id']);
+    });
+
+    it("include: ['listCustomers'] exposes exactly that action", async () => {
+        const { def, handlers } = await createOpenApiProviderFactory()(
+            ctx({ providerConfig: { spec: crm, include: ['listCustomers'] } }),
+        );
+        expect(def.actions?.map((a) => a.key)).toEqual(['listCustomers']);
+        expect(Object.keys(handlers)).toEqual(['listCustomers']);
+    });
+
+    it('names an operation without an operationId by its generated method_path key', async () => {
+        const { def } = await createOpenApiProviderFactory()(
+            ctx({ providerConfig: { spec: crm, include: ['delete_customers_id', 'createCustomer'] } }),
+        );
+        // Document order, not include order — the allowlist filters, it does not reorder.
+        expect(def.actions?.map((a) => a.key)).toEqual(['createCustomer', 'delete_customers_id']);
+    });
+
+    it("include: ['nope'] refuses at materialization, naming the entry and the document's keys", async () => {
+        const err = await refusal(
+            createOpenApiProviderFactory()(ctx({ providerConfig: { spec: crm, include: ['listCustomers', 'nope'] } })),
+        );
+        expect(err.message).toContain("connector 'pets' providerConfig.include names 'nope', which the OpenAPI document does not carry");
+        expect(err.message).toContain("'listCustomers', 'createCustomer', 'delete_customers_id'");
+        expect(err.message).not.toContain("'listCustomers', which");
+    });
+
+    it('an operation that has an operationId is not named by its method_path key', async () => {
+        const err = await refusal(
+            createOpenApiProviderFactory()(ctx({ providerConfig: { spec: crm, include: ['get_customers'] } })),
+        );
+        expect(err.message).toContain("names 'get_customers', which the OpenAPI document does not carry");
+    });
+
+    it('refuses an include that is not an array of non-empty strings, before the document is fetched', async () => {
+        let fetched = 0;
+        const fetchImpl = (async () => {
+            fetched++;
+            return { ok: true, status: 200, json: async () => crm } as unknown as Response;
+        }) as unknown as typeof fetch;
+        const factory = createOpenApiProviderFactory({ fetchImpl });
+        for (const include of ['listCustomers', ['listCustomers', 7], [''], { listCustomers: true }, null]) {
+            const err = await refusal(factory(ctx({ providerConfig: { spec: 'https://crm.example.com/openapi.json', include } })));
+            expect(err.message, JSON.stringify(include)).toContain("connector 'pets' providerConfig.include must be an array of operation keys");
+        }
+        expect(fetched).toBe(0);
+    });
+
+    it('an empty include admits no operation, as an empty mcp include admits no tool', async () => {
+        const { def } = await createOpenApiProviderFactory()(ctx({ providerConfig: { spec: crm, include: [] } }));
+        expect(def.actions).toEqual([]);
+    });
+
+    describe('through a real boot (AutomationServicePlugin + ConnectorOpenApiPlugin)', () => {
+        async function boot(include: unknown) {
+            const declared = [
+                { name: 'crm_api', label: 'CRM API', type: 'api', provider: 'openapi', providerConfig: { spec: crm, include } },
+            ];
+            const kernel = new LiteKernel({ logger: { level: 'silent' } } as never);
+            kernel.use(new AutomationServicePlugin());
+            kernel.use({
+                name: 'test.connector-metadata',
+                type: 'standard',
+                version: '1.0.0',
+                dependencies: ['com.objectstack.service-automation'],
+                async init(c: { registerService(name: string, service: unknown): void }) {
+                    c.registerService('objectql', {
+                        registry: { listItems: (type: string) => (type === 'connector' ? declared : []) },
+                    });
+                },
+                async start() {},
+            } as never);
+            kernel.use(new ConnectorOpenApiPlugin());
+            return kernel;
+        }
+
+        it('a declared include reaches GET /connectors as exactly the listed action', async () => {
+            const kernel = await boot(['listCustomers']);
+            try {
+                await kernel.bootstrap();
+                const engine = kernel.getService<AutomationEngine>('automation');
+                const crmApi = engine.getConnectorDescriptors().find((d) => d.name === 'crm_api');
+                expect(crmApi?.state).toBe('ready');
+                expect(crmApi?.actions.map((a) => a.key)).toEqual(['listCustomers']);
+            } finally {
+                await kernel.shutdown().catch(() => {});
+            }
+        });
+
+        it('an unknown include entry fails the boot instead of degrading', async () => {
+            const kernel = await boot(['nope']);
+            try {
+                await expect(kernel.bootstrap()).rejects.toThrow(/providerConfig\.include names 'nope'/);
+                const engine = kernel.getService<AutomationEngine>('automation');
+                expect(engine.getConnectorDegradedReason('crm_api')).toBeUndefined();
+            } finally {
+                await kernel.shutdown().catch(() => {});
+            }
+        });
+    });
+});
@@ -8,6 +8,7 @@ import type {
 import { ConnectorUpstreamUnavailableError } from '@objectstack/spec/integration';
 import {
   createOpenApiConnector,
+  operationActionKey,
   type OpenApiDocument,
   type RestAuth,
 } from './openapi-connector.js';
@@ -50,8 +51,40 @@ interface OpenApiProviderConfig {
   spec?: unknown;
   /** Override the base URL (else the document's `servers[0].url`). */
   baseUrl?: unknown;
+  /**
+   * Optional operation allowlist — only the listed operations become actions,
+   * the same allowlist meaning as the `mcp` provider's `include` (tool names
+   * there, action keys here). Each entry is an operation's `operationId`, or
+   * the generated `method_path` key (`get_pets_id`) for an operation the
+   * document gives no `operationId` — i.e. exactly the action key the
+   * operation is exposed under. An entry naming an operation the document
+   * does not carry is a configuration fault (see {@link resolveIncludeList}).
+   */
+  include?: unknown;
+}
+
+/**
+ * Validate `providerConfig.include`: absent ⇒ every operation; otherwise an
+ * array of non-empty strings. Any other shape is a configuration fault, thrown
+ * plain (fatal at boot, a skipped entry on reload) — an allowlist that silently
+ * dropped an entry it could not read would expose the very operations the
+ * author meant to keep out, or hide the one they meant to keep in.
+ */
+function resolveIncludeList(raw: unknown, connectorName: string): readonly string[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw) || raw.some((entry) => typeof entry !== 'string' || entry.length === 0)) {
+    throw new Error(
+      `connector-openapi provider: connector '${connectorName}' providerConfig.include must be an array of ` +
+        `operation keys (strings): each an operationId, or the generated method_path key for an operation ` +
+        `without one.`,
+    );
+  }
+  return raw as string[];
 }
 
+/** How many of the document's action keys an unknown-entry refusal lists. */
+const INCLUDE_REFUSAL_KEY_SAMPLE = 20;
+
 /**
  * Refuse a document that is not OpenAPI 3.x — a Swagger 2.0 document
  * (`swagger: "2.0"`) included. The generator maps the 3.x shape only
@@ -204,8 +237,13 @@ async function loadOpenApiDocument(
  * generates for a hand-wired OpenAPI connector — one action per operation over a
  * static-auth HTTP transport, with the resolved `auth` applied.
  *
+ * `providerConfig.include` (optional) narrows the actions to an allowlist of
+ * operation keys, through the generator's own `include` predicate.
+ *
  * Hard-fails on invalid config (missing spec, a wrong spec URL, an unparseable
- * document, a document that is not OpenAPI 3.x, a bad base URL), so a misconfigured instance fails boot loudly. A
+ * document, a document that is not OpenAPI 3.x, a bad base URL, an `include`
+ * that is not a string array or names an operation the document does not
+ * carry), so a misconfigured instance fails boot loudly. A
  * remote spec URL that is merely unreachable / transiently failing instead
  * degrades the instance and retries (#3049) — see {@link loadOpenApiDocument}.
  */
@@ -217,20 +255,54 @@ export function createOpenApiProviderFactory(deps: OpenApiProviderDeps = {}): Co
         `connector-openapi provider: connector '${ctx.name}' providerConfig.baseUrl must be a string when set.`,
       );
     }
+    const includeList = resolveIncludeList(cfg.include, ctx.name);
     const document = await loadOpenApiDocument(cfg.spec, deps.fetchImpl, ctx);
     const auth = ctx.auth as ResolvedConnectorAuth | undefined as RestAuth | undefined;
-    return createOpenApiConnector({
+    // The allowlist rides the generator's own `include` predicate; every key
+    // the document offers is recorded on the way, so an entry nothing matched
+    // can be named in the refusal below.
+    const documentKeys: string[] = [];
+    const include = includeList
+      ? (op: Parameters<typeof operationActionKey>[0]) => {
+          const key = operationActionKey(op);
+          documentKeys.push(key);
+          return includeList.includes(key);
+        }
+      : undefined;
+    const bundle = createOpenApiConnector({
       name: ctx.name,
       label: ctx.label,
       description: ctx.description,
       document,
       baseUrl: typeof cfg.baseUrl === 'string' ? cfg.baseUrl : undefined,
       auth,
+      include,
       // ADR-0049 · #18975 — the authored resilience policy, already resolved by
       // the materializer, reaches the transport this bundle closes over.
       retryConfig: ctx.retryConfig,
       requestTimeoutMs: ctx.requestTimeoutMs,
       fetchImpl: deps.fetchImpl,
     });
+    if (includeList) {
+      // An entry naming an operation the document does not carry is a
+      // configuration fault, thrown plain — fatal at boot, a skipped entry on
+      // reload. Ignoring it would bring the instance up without the action
+      // the author listed (a typo, or an operation the upstream renamed or
+      // removed), and the first sign would be a flow failing at run time.
+      const offered = new Set(documentKeys);
+      const unknown = [...new Set(includeList)].filter((entry) => !offered.has(entry));
+      if (unknown.length > 0) {
+        const sample = [...offered].slice(0, INCLUDE_REFUSAL_KEY_SAMPLE);
+        const more = offered.size > sample.length ? `, … ${offered.size - sample.length} more` : '';
+        throw new Error(
+          `connector-openapi provider: connector '${ctx.name}' providerConfig.include names ` +
+            `${unknown.map((entry) => `'${entry}'`).join(', ')}, which the OpenAPI document does not carry. ` +
+            `Each entry must be an operationId, or the generated method_path key for an operation without one; ` +
+            `the document offers ${offered.size} operation key(s): ` +
+            `${sample.map((key) => `'${key}'`).join(', ')}${more}.`,
+        );
+      }
+    }
+    return bundle;
   };
 }