ADR-082: The offered-connector set is the one gate

Status: ACCEPTED, 2026-11-06 (Arch-authored). This ADR records rulings already made and landed (decisions.log, 2026-10-30 to 2026-11-05) as one decision, so the next change to the offer set has a single place to read. It changes no code. Related issues: #2236, #2237, #2245, #2238, #2284, #1481, #2262. Law it serves: ADR-080 (code decides permission), ADR-081 (whose token serves a request).

Context

The beta (outside testers from 2026-10-31) offers two connectors, GitHub and Google Calendar. Slack and Notion exist in the code, with routes, stored credentials and readers, but they are not offered. Within one week, four separate defects showed the same gap: each surface kept its own idea of what was offered.

A hand-kept list on each surface drifts, and each drift either offers something we don’t support or reads a credential we said we wouldn’t.

Decision

D1. One predicate, read at call time

services/integrations/integration_status_service.py holds it:

The set is BETA_OFFERED_CONNECTORS (code-fixed, {"github", "calendar"} today), plus STAGING_ONLY_OFFERED_CONNECTORS when, and only when, FLY_APP_NAME == "piper-morgan-staging".

Rules:

D2. Every surface reads that predicate, and none keeps a second list

Surface Reads it how
Connect, OAuth-start, OAuth-callback and credential-save routes (web/api/routes/settings_integrations.py, web/api/routes/setup.py) refuse_unless_offered(name) as the route body’s first statement: HTTP 409 with NOT_OFFERED_MESSAGE, before any redirect, validation or write (#2237, 10-30 20:50)
Integrations page (templates/integrations.html) window.__OFFERED_CONNECTORS__ from web/api/routes/ui.py. The page’s OAUTH_INTEGRATIONS and API_KEY_INTEGRATIONS say only how a connector connects, and every use is behind isOffered. The page fails closed
Chat capability reply and floor identity context (capability_answer.py, canonical_handlers.py) offered_connectors(), one key-based filter (#2245, 10-31 19:34; #2236, 10-30 19:05)
Chat connect pointers (chat_pointers.py) connector_offered. A non-offered ask gets the pointer to what is offered (NOT_OFFERED_ALTERNATIVE)
Credential use-path reads (D3) connector_offered

A new surface that shows, guards or lists connectors reads the predicate. A surface that needs a connector’s kind (OAuth or API key) may keep that as data, but never as a second offer list.

D3. A non-offered connector’s stored credential is not read for use

Stored credentials survive a descope, because accounts connected before it. The gate sits at the connector’s one use-path read, not at each reader (#2284, 11-05 06:28; validated 10:41 on 865e06c3ba):

Named exceptions, which may read a non-offered credential:

A ratchet pins which modules may name the Slack keychain slots (TestSlackSlotRatchet).

D4. Offering a connector is one code change, made with its checks

To offer a connector for real:

Which connectors are offered is product scope (PPM and xian); this ADR fixes only how an offer takes effect.

Consequences

Evidence