feat(spec)!: remove the per-provider connector "template" cluster (#4480) (#4500)

BREAKING CHANGE: @objectstack/spec/integration no longer exports the six
per-provider connector schemas — DatabaseConnectorSchema,
FileStorageConnectorSchema, GitHubConnectorSchema, MessageQueueConnectorSchema,
SaasConnectorSchema, VercelConnectorSchema — nor their ~100 sub-schema/type/
example exports (2,672 lines). The six generated reference pages go with them.

#4480 started as one dead key (DatabaseConnector.readReplicaConfig, found
while removing datasource.readReplicas in #4468) and scoped out to the whole
cluster: zero consumers for all six schemas. Nothing in the monorepo imported
any of them — not the automation engine (engine.registerConnector validates
against ConnectorSchema from connector.zod.ts, engine.ts:1379), not the
`connectors:` stack collection (DeclarativeConnectorEntrySchema), not even
their own module's live half.

They were the losing side of a decided architecture fight, left standing.
ADR-0023 rejected hand-modelling each external system's shape inside the spec;
ADR-0097's connector protocol does the opposite — provider shapes come from
the provider itself (connector-openapi materializes instances from an OpenAPI
document, connector-mcp from an MCP server). The templates hardcoded
Postgres/S3/GitHub/RabbitMQ/Vercel shapes nothing would ever read, and were
semantically wrong where they overlapped the live platform:
DatabaseConnectorSchema modelled "tables to sync", CDC, and readReplicaConfig
— read-replica routing declared a SECOND time, down to a `weight` field for a
load balancer that does not exist. External-database access is datasource
federation (ADR-0015), which is live and is not a connector.

The removal kit:

- integration/index.ts: six export lines removed; module header now records
  the decision so the next reader finds the ADR trail, not a gap
- json-schema.manifest.json: 47 entries deleted deliberately (the gen:schema
  ratchet's documented retirement path)
- authorable-surface.json: 365 lines deleted deliberately (gate (a)'s strict-
  removal trip wire, whole-cluster edition)
- api-surface.json regenerated from the rebuilt dist
- docs: six connector-* reference pages deleted, plus three sibling pages
  (message-queue/object-storage/tenant under references/integration) whose
  entire content documented deleted-file exports; section meta + index
  regenerated; hand-written tables in references/index.mdx and
  getting-started/quick-reference.mdx rewritten around the one live protocol
- PROTOCOL_MAP.md: six rows collapsed into the connector.zod.ts row (the
  protocol-map link test is what caught this surface)
- v17 release notes: dead-clusters table row
- changeset: major, with the no-migration rationale (these schemas validated
  no stored metadata, so there is no D2 conversion to register — nothing to
  rewrite)

No runtime behaviour changes: the ADR-0097 path — ConnectorSchema,
DeclarativeConnectorEntrySchema, the provider contract, connector-descriptor,
connector auth — is untouched, which the service-automation suite (609 tests)
confirms.

Follow-up filed: #4499 — automation/trigger-registry.zod.ts carries a THIRD
declaration of the same business need (its own ConnectorSchema cluster, ~440
lines, zero runtime consumers; the engine imports integration's schema).
Kept out of this PR: that file mixes the dead cluster with trigger-registry
exports that need individual verdicts.

Closes #4480


Claude-Session: https://claude.ai/code/session_01WsgTqRF58HsQYKLsrZ5pQY

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/connector-template-cluster-removed.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/spec': major
+---
+
+The per-provider connector "template" cluster is removed (#4480, ADR-0049)
+
+`@objectstack/spec/integration` no longer exports the six per-provider
+connector schemas and their sub-schema/type/example clusters (~110 exports,
+2,672 lines):
+
+- `DatabaseConnectorSchema` (+ `DatabaseProviderSchema`, `DatabasePoolConfigSchema`,
+  `SslConfigSchema`, `CdcConfigSchema`, `DatabaseTableSchema`, the three
+  `*ConnectorExample` constants)
+- `FileStorageConnectorSchema` (+ bucket/versioning/multipart/filter configs, examples)
+- `GitHubConnectorSchema` (+ repository/commit/PR/actions/release/issue configs, examples)
+- `MessageQueueConnectorSchema` (+ its queue/topic/consumer configs, examples)
+- `SaasConnectorSchema` (+ examples)
+- `VercelConnectorSchema` (+ its deployment/domain/env configs, examples)
+
+The six generated reference pages under `docs/references/integration/` go with
+them.
+
+**Why removal, not completion.** These files were the losing side of an
+architecture decision the same module's live half already records. ADR-0023
+rejected hand-modelling each external system's shape inside the spec —
+"re-inventing OpenAPI inside this schema" — and ADR-0097's connector protocol
+does the opposite: one `ConnectorSchema`, with provider shapes coming from the
+provider itself (`connector-openapi` materializes instances from an OpenAPI
+document, `connector-mcp` from an MCP server). The templates hardcoded
+Postgres/S3/GitHub/RabbitMQ/Vercel shapes into spec files nothing ever read:
+
+- `engine.registerConnector()` validates against `ConnectorSchema` from
+  `connector.zod.ts` — never the templates
+- the `connectors:` stack collection parses `DeclarativeConnectorEntrySchema` —
+  never the templates
+- nothing else in the monorepo, objectui included, imported any of the six
+
+They were also semantically wrong where they overlapped the live platform:
+`DatabaseConnectorSchema` modelled "tables to sync", CDC, and `readReplicaConfig`
+— a second, independent declaration of read-replica routing (the first,
+`datasource.readReplicas`, was removed in #4468), complete with a `weight`
+field for a load balancer that does not exist. External-database access is
+datasource federation (ADR-0015), which is live and is not a connector.
+
+**Migration.** There is nothing to migrate: these schemas validated no stored
+metadata (the `connectors:` collection never used them) and no runtime read
+their output. If you imported one as a TypeScript type for your own code,
+model your provider config yourself, or — the supported path — declare a
+provider-bound connector instance and let connector-openapi / connector-mcp
+derive the shape:
+
+```ts
+// before (typed against a dead spec export)
+import { DatabaseConnector } from '@objectstack/spec/integration';
+
+// after (the live protocol)
+import { Connector, DeclarativeConnectorEntry } from '@objectstack/spec/integration';
+```
+
+The base protocol — `ConnectorSchema`, `DeclarativeConnectorEntrySchema`, the
+ADR-0097 provider contract, connector-descriptor, connector auth — is
+unchanged.

content/docs/getting-started/quick-reference.mdx

@@ -193,19 +193,18 @@ Environments, marketplace, licensing, and multi-tenancy.
 | **[Plugin Security](/docs/references/cloud/plugin-security)** | `plugin-security.zod.ts` | PluginSecurityProtocol, SBOM | Plugin security policies |
 | **[Tenant](/docs/references/cloud/tenant)** | `tenant.zod.ts` | Tenant | Multi-tenancy isolation |
 
-## Integration Protocol (7 schemas)
+## Integration Protocol (1 schema)
 
-External system connectors and adapters.
+External system connectors — one protocol (ADR-0097): a connector entry is
+either a catalog descriptor or a provider-bound instance that a generic
+executor (connector-openapi / connector-mcp) materializes at boot. The
+per-provider schema "templates" (SaaS / database / file-storage /
+message-queue / GitHub / Vercel) were removed in #4480: provider shapes come
+from the provider itself, not from hand-written spec files.
 
 | Protocol | Source File | Key Schemas | Purpose |
 |:---------|:-----------|:------------|:--------|
-| **[Connector](/docs/references/integration/connector)** | `connector.zod.ts` | Connector | Generic connector interface |
-| **[SaaS Connector](/docs/references/integration/connector)** | `connector/saas.zod.ts` | SaaSConnector | SaaS integrations |
-| **[Database Connector](/docs/references/integration/connector)** | `connector/database.zod.ts` | DatabaseConnector | Database adapters |
-| **[File Storage](/docs/references/integration/connector)** | `connector/file-storage.zod.ts` | FileStorageConnector | Cloud storage |
-| **[Message Queue](/docs/references/integration/message-queue)** | `connector/message-queue.zod.ts` | MessageQueueConnector | Queue integrations |
-| **[GitHub](/docs/references/integration/connector)** | `connector/github.zod.ts` | GitHubConnector | GitHub API integration |
-| **[Vercel](/docs/references/integration/connector)** | `connector/vercel.zod.ts` | VercelConnector | Vercel deployment |
+| **[Connector](/docs/references/integration/connector)** | `connector.zod.ts` | Connector | The connector protocol — auth, sync, webhooks, rate limiting |
 
 ## Shared Protocol (5 schemas)
 

content/docs/references/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Complete reference of all 139 ObjectStack protocol specifications
+description: Complete reference of all 133 ObjectStack protocol specifications
 ---
 
 # Protocol Reference
@@ -30,7 +30,7 @@ These reference pages are **auto-generated** from the Zod source files in `packa
 | [QA Protocol](#qa-protocol) | 1 | Test Suites and BDD Scenarios |
 | [Studio Protocol](#studio-protocol) | 1 | Studio plugin development |
 
-**Total: 175 Zod schemas** (across 14 protocol modules + 1 root stack schema)
+**Total: 169 Zod schemas** (across 14 protocol modules + 1 root stack schema)
 
 ---
 
@@ -313,19 +313,18 @@ Defines marketplace and multi-tenancy capabilities.
 ## Integration Protocol
 
 **Location:** `packages/spec/src/integration/`
-**Count:** 7 schemas
+**Count:** 1 schema
 
-Defines external system connectors and adapters.
+Defines external system connectors — one protocol (ADR-0097). A connector
+entry is either a catalog descriptor or a provider-bound instance that a
+generic executor (connector-openapi / connector-mcp) materializes at boot.
+The per-provider "templates" (`connector/saas.zod.ts` and five siblings) were
+removed in #4480: they hand-modelled each external system's shape inside the
+spec, which ADR-0023 rejected, and nothing ever consumed them.
 
 | File | Schema | Purpose |
 | :--- | :--- | :--- |
-| `connector.zod.ts` | `ConnectorSchema` | Generic connector interface |
-| `connector/saas.zod.ts` | `SaaSConnectorSchema` | SaaS platform connectors (Salesforce, HubSpot, etc.) |
-| `connector/database.zod.ts` | `DatabaseConnectorSchema` | Database connection adapters |
-| `connector/file-storage.zod.ts` | `FileStorageConnectorSchema` | Cloud storage connectors (S3, Azure Blob, etc.) |
-| `connector/message-queue.zod.ts` | `MessageQueueConnectorSchema` | Message queue integrations (RabbitMQ, Kafka, etc.) |
-| `connector/github.zod.ts` | `GitHubConnectorSchema` | GitHub API integration |
-| `connector/vercel.zod.ts` | `VercelConnectorSchema` | Vercel deployment integration |
+| `connector.zod.ts` | `ConnectorSchema` | The connector protocol — auth, sync, webhooks, rate limiting |
 
 **Learn more:** [Integration Protocol Reference](/docs/references/integration)