A plugin that needs another plugin to do something — Sales opening a private channel in Chat —
calls it through a contract: a typed interface the provider declares and implements, looked up
in core’s contract registry at the moment of use.
Declare. The provider’s manifest lists contracts.provides: [{ name: chat, version: 1.1.0 }];
the caller’s lists contracts.requires: [{ name: chat, version: ^1.1.0, optional: true }] — a
range, or a bare version meaning the same major. optional: true means the caller works without
it; extension: true (on both sides) makes it an extension point with many providers.
Describe. The interface lives in the provider’s contracts package: ChatApi in
@antfabric-contracts/chat. Types only, no code.
Provide. At start-up the provider registers a factory:
get returns null when an optional contract’s provider is not installed. The caller must
degrade: Sales hides “Discuss in Chat” and skips the “deal won” post. For an extension point,
getAll<T>(name) returns every provider ({ pluginId, version, api }), sorted by plugin id.
A plugin can provide only contracts in its provides, and use only those in its requires.
Anything else throws at the call.
One provider per contract, unless it is an extension point. Codegen refuses two providers, a
provider version a caller cannot use, and a required (not optional) contract nobody provides.
The factory learns who calls (caller.pluginId), so the provider keeps each caller to its own
records. Chat prefixes record-channel keys with the caller’s id.
Core attaches the person the call is for: await caller.actor() is the signed-in person
during a request, the workflow’s user in an Activity or event handler, or null. Don’t trust an
actor the caller passes in. Chat compares it with caller.actor() and refuses a mismatch.
Methods in actorRequired are refused by core (403) when there is no actor.
No route guard runs, so the provider checks that person’s permissions itself.
The provider’s code runs in the provider’s module, with the provider’s database role.
Contracts work in the workers too: plugin modules boot there, so Activities call them through
sdk.contracts.
Contracts stay in-process: an AsyncIterable result or an AbortSignal argument may cross them.
Never call a contract inside your own database transaction — the provider has its own.
Contracts change additively within a major version; a breaking change is a new major, offered
side by side until callers move.