Extend a connector

Live connectors have dependents: bindings in installs, environments, approval policies, and human habits. The source gives hard rules. Follow them literally.

Work through bindings, not around them

Bindings live in install settings.object_mappings, scoped to org, package, and connection, with identity namespace binding:<uuid> in ai.connector_object_map. Extending means:

• New and changed mappings written as bindings with all three coordinates, never a floating mapping
• Identity namespace preserved: existing binding:<uuid> entries keep their meaning; new bindings get new UUIDs
• Client-safe shape respected (object-mapping-contract.ts). The shared UI and Admin API stay the contract surface.
• Changes verified per affected org, package, and connection, not just globally

Where bindings live: the install at /automations/connectors/[packageKey]. Mappings below are the SDK contract, not this screen.

Binding contract recap: bindings in install settings.object_mappings (org, package, connection); identity binding:<uuid> in ai.connector_object_map; destination example targetObject: 'work-items' with workItemTypeId; never retired tasks/deliverables; never expose applyConnectorMappedRecord unauthenticated. Full version: Concepts.

Destinations: catalog only, retired ones never

• Destination example from source: targetObject: 'work-items' with workItemTypeId. The pattern for valid targets via target-catalog.ts.
• Never use the retired tasks/deliverables destinations. An extension that re-targets retired destinations is broken on arrival, regardless of what old docs or memory suggest.

Additive first, re-verify always

• Add capabilities (new objects, properties, mappings) without disturbing existing bindings.
• Never silently widen scope: a read becoming a write-equivalent, or new data boundaries, are breaking changes. Treat them as new proposals with fresh approval design and fresh contract-test evidence (create, update, retry, pause).
• Re-run verification per affected tenant after the change lands.

The never list (from source)

• Never expose applyConnectorMappedRecord unauthenticated. Authorized runners only. No public route, no unguarded call path.
• Never revive connector-sync-runner. New scheduling via function-catalog Inngest functions.
• Never advance watermarks on partial failure (failed === 0 or the watermark holds).
• Never present Salesforce scaffolds as implementations.
• Never promise outbound HubSpot writes. They remain disabled.
• Never paste credentials anywhere in the change process. Product flow only (Auth).

Anything about versioning mechanics or deprecation policy beyond this: not in pasted sources. Confirm in the product repo before documenting.