An integration factors reusable protocol logic into inspectable Template/Expression definitions. It does not register a native handler with the executor.
Specify public input/output, pagination, encoding, known failure behavior and external-write
uncertainty. Implement the protocol in integrations/providers/src/declarative/ using generic
HTTP, loops, data transforms, clock/wait and protected crypto operations. Pure chain/protocol
codecs may come from Domain's public definitions; application-specific business policy stays out.
import { literal } from '@processos/contracts/language';
import type { Template } from '@processos/contracts/language';
const request: Template = {
tag: 'http',
request: literal({url: 'https://example.invalid/api/items', method: 'GET'}),
};
The example has no credentials and is not deployment-approved. Real definitions use configured capability references and constrained destinations. Never place tokens, private keys, signed raw transactions or OAuth assertions in ordinary context/history. The protected subsystem can carry approved encrypted handles through signing, derivation and exact HTTP placement.
Binding a public name to an endpoint/credential is operational configuration, not a new runtime opcode. A missing credential should fail explicitly when the operation needs it; it must not change the immutable definition merely because a build machine lacks secrets. Follow deployment bindings for origin/path/method policies, keyrings and execution approvals.
Authoring factories may compose library definitions. Serialized output must run without installing Integrations or Domain in the generic executor. Configuration shapes can be exported from the Integration authoring entrypoint, but must not import the app graph model.
Soft notification failure, hard process failure and known retryable failure are different contracts. Express them in the returned syntax. An uncertain transport failure is handled by the journal's hold, not caught and disguised as safe retry. Preserve partial committed writes in evidence where relevant.
Test synthetic request/response sequences, malformed data, pagination limits, policy denial, serialization/restart, idempotency assumptions, uncertainty and exact output/audit shapes. Existing Dune, Sheets and Safe definitions provide examples; their passing tests do not prove a new provider's semantics. See add an activity for optional editor notation and verification for the full gate.