govoplan-connectors/docs/GOVERNED_CONNECTOR_CONFIGURATION.md

Governed Connector Configuration

GovOPlaN connectors should make integration behavior inspectable and testable. The target is not hardcoded glue hidden in module code, but governed connector definitions with schemas, mappings, test runs, simulation, versioning, and audit-visible execution.

Connector Definition

A connector definition should describe:

• provider type and protocol
• endpoint and credential requirements
• supported capabilities
• input and output schemas
• mapping and transformation versions
• validation rules
• dry-run and test operations
• privacy and retention classification
• expected events and audit records
• operational limits and retry behavior

Provider-specific code may still be required, but the configured integration logic should remain visible and reviewable.

Runtime Expectations

Connectors supports the generic governed-definition and simulation portion of:

• discovery where possible
• typed configuration through UI-managed controls
• secret references instead of plaintext secrets
• dry-run plans before writes
• simulation with sample payloads
• provenance for consumed and produced data
• idempotent external writes where supported
• quarantine/manual-review state for unsafe or ambiguous results

Configuration packages may install connector definitions, but local overrides must be protected from accidental package updates.

Implemented Runtime Slice

The module now persists tenant-scoped connector definitions as immutable revisions. A governed definition explicitly validates its provider, protocol, capabilities, input/output schemas, mapping version and rules, validation, preview metadata, audit expectations, classification, retention, limits, and retry policy. Definitions record whether they are locally owned or supplied by a named package.

Configurations pin a definition revision. They store an endpoint and a secret reference, never credentials embedded in the URL. Tenant-local override values are merged into the pinned definition and every overridden leaf is exposed as a protected path. Installing a later package revision only marks the configuration as having an update available. Adoption is an explicit, optimistically locked action that reapplies the protected overrides over the new package revision.

The generic execution surface supports bounded dry-runs and simulations. Each run has a caller idempotency key and retains hashes of its inputs and effective configuration together with definition, configuration, mapping, external revision, actor, classification, and retention provenance. Samples redact the definition's protected fields. Ambiguous uniqueness results follow the configuration's policy and become either:

• manual_review with a pending decision;
• quarantined until an administrator decides; or
• rejected without a review queue entry.

Review decisions require a reason and are audited. The generic runtime stops at deterministic preview evidence: provider-specific adapters remain responsible for live external writes and must satisfy the Core connector recovery contract before claiming write maturity.

The Connector governance administration page follows the shared workspace archetype. Reload and Save stay in the semantic action bar, dirty navigation is guarded, package adoption is a separate action, and simulation results and review decisions remain visibly distinct from configuration editing.

Relationship To Datasources And Dataflow

Recurring extraction and transformation should start as configuration across connectors, files, workflow, reporting, and templates. Create dedicated datasource or dataflow modules only when repeated source-catalog, lineage, mapping, scheduling, or publication contracts clearly outgrow connector ownership.