Integration Guidelines

Integrations are built only after core functionality is complete and stable. They connect the product to external tools, providers, services, protocols, or ecosystems without redefining the product's core behavior.

An integration is an adapter to a product capability, not an alternate product architecture.

Required outcome

Each integration must:

• extend a documented core capability;
• use a stable core interface;
• declare its supported capability set;
• remain isolated from unrelated core workflows;
• fail without corrupting core state;
• use least-privilege identity;
• expose actionable diagnostics;
• define compatibility, ownership, and lifecycle behavior.

Integration proposal

Before implementation, document:

• the user outcome enabled by the integration;
• the core capability it extends;
• why the integration belongs in the product;
• the external system and supported versions;
• required credentials and permissions;
• data exchanged and its sensitivity;
• expected availability and rate limits;
• cost implications;
• failure and recovery behavior;
• ownership and maintenance responsibility;
• exit or removal strategy.

An integration without a named owner and supported contract must not be shipped.

Adapter boundary

External concepts must be translated at a narrow adapter boundary. The adapter owns:

• authentication with the external system;
• request and response translation;
• pagination, retries, and rate-limit handling;
• provider-specific identifiers;
• capability detection;
• normalized error mapping;
• external API version compatibility;
• provider-specific telemetry.

Core code must not construct raw provider requests or branch repeatedly on provider names.

Desktop applications

A Wisent desktop application is an independent user experience, not a wrapper around the product's command-line interface. It reaches its product only through:

• a loopback HTTP/JSON API served by the product;
• direct reads of local state files the product owns;
• a library linked into the application.

The interface never renders shell commands, install instructions, or environment-variable lines. When the product offers no API for a capability the desktop needs, the capability is added to the product's API; it is not exposed to the user as a copyable command. Where no API exists yet, the interface states the fact in plain prose.

Capability model

Every integration must publish an accurate capability declaration. Distinguish:

• implemented and supported;
• partially implemented;
• externally managed;
• unavailable;
• planned but not present.

Unsupported operations must fail explicitly before mutation. Do not emulate a missing capability with a weaker or unsafe behavior unless that fallback is part of the documented product contract.

Configuration

Integration configuration must be namespaced, validated, and optional unless the README defines the integration as core.

Document:

• required and optional fields;
• environment overrides;
• precedence rules;
• secret references;
• endpoint and region selection;
• timeout and retry policy;
• feature or capability flags;
• restart requirements.

The product must start and deliver unrelated core workflows when an optional integration is unconfigured.

Authentication and authorization

Use the narrowest identity supported by the external system. Prefer managed identity, workload identity, OAuth delegation, or scoped service credentials over static administrator keys.

For every credential, define:

• consumer identity;
• granted actions;
• resource scope;
• storage location;
• rotation procedure;
• revocation procedure;
• audit source.

Credentials must not appear in configuration committed to source, request payloads, durable product state, logs, or error messages.

Never silently reuse a broader control-plane credential for a workload or integration client.

Data contract

Define all data crossing the boundary:

• schema and encoding;
• identifiers and normalization;
• units and timestamps;
• size limits;
• ordering guarantees;
• pagination;
• deduplication and idempotency keys;
• retention;
• data residency;
• encryption in transit and at rest;
• deletion and privacy obligations.

Validate external data before it enters authoritative core state. Treat external responses as untrusted input.

Reliability

The integration must define behavior for:

• timeout;
• connection failure;
• authentication failure;
• authorization failure;
• rate limiting;
• quota exhaustion;
• malformed response;
• partial success;
• duplicate delivery;
• stale data;
• external API change;
• provider outage.

Retries must be bounded, observable, and limited to safe operations. Use idempotency keys or compare-and-swap semantics where duplication would be harmful.

Circuit breaking, backoff, or queueing may protect the core, but must not turn permanent errors into infinite hidden retries.

Failure isolation

An unavailable optional integration must not:

• prevent unrelated core startup;
• corrupt shared state;
• block unrelated workflows indefinitely;
• trigger an unsafe fallback;
• cause credentials from another integration to be reused;
• erase the evidence needed for recovery.

Persist enough state to resume safely after the integration returns.

Observability

Expose:

• integration health;
• authenticated identity or credential source without secret material;
• request success and failure classification;
• latency and rate-limit state;
• quota or capacity state;
• retry and circuit-breaker state;
• last successful synchronization;
• version or capability mismatch;
• user-visible remediation.

Avoid high-cardinality identifiers and raw external payloads in telemetry unless explicitly required and protected.

Compatibility and upgrades

Pin or constrain supported external API and SDK versions. Define how compatibility is detected and what happens when the external service introduces a breaking change.

Integration changes that alter a public product contract follow the product versioning policy. Provider-only corrections may remain compatible when the normalized core contract is unchanged.

Lifecycle and removal

Define installation, enablement, disablement, credential revocation, data cleanup, and removal. Disabling an integration must leave authoritative core state understandable and recoverable.

If the external product is deprecated, document migration to an alternative or the loss of capability. Do not leave dormant credentials or background jobs after removal.

Prohibited patterns

Do not:

• make an optional integration a hidden startup dependency;
• expose raw external SDK types as the core product API;
• scatter provider-name conditionals through core code;
• use an administrator credential because scoped setup is inconvenient;
• retry every error indefinitely;
• treat HTTP success as semantic success without validating the response;
• ignore pagination or rate limits;
• write external data directly into authoritative state without validation;
• claim support based only on authentication or a single read operation;
• use mocks that bypass the adapter boundary as the only evidence of behavior.
• ship a desktop application that builds command lines for the product CLI or renders command strings in its interface;

Completion gate

An integration is complete only when:

• it maps to a stable documented core capability;
• its capability declaration is accurate;
• configuration and credentials are scoped and validated;
• data contracts and limits are explicit;
• failures are normalized, isolated, and recoverable;
• retries and idempotency are safe;
• compatibility and ownership are documented;
• enable, disable, and removal paths exist;
• the core product remains usable when the integration is unavailable.