diff --git a/docs/CONCEPT.md b/docs/CONCEPT.md index 7874b0c..39defa1 100644 --- a/docs/CONCEPT.md +++ b/docs/CONCEPT.md @@ -25,6 +25,20 @@ Detailed follow-up documents: - [OpenProject connector concept](OPENPROJECT_CONNECTOR.md) - [OpenDesk integration map](OPENDESK_INTEGRATION_MAP.md) +## Shared runtime boundary + +Connector transports use the versioned Core runtime contract for bounded dry +runs and diagnostics. Connectors owns endpoint discovery, authentication +hand-off, protocol reads, retry/backoff, and source health. A consuming module +owns domain mappings and mutations: Addresses, for example, owns contact and +vCard semantics even when Connectors supplies reusable LDAP, CardDAV, Exchange, +or Google transport patterns. + +Dry runs carry an immutable input hash, source revision and fingerprint, +redacted effects, diagnostics, truncation state, and an apply token. Apply must +reject a changed input or source revision. URLs and diagnostics never contain +credential material; they retain only credential-envelope references. + ## Ownership The module owns: diff --git a/src/govoplan_connectors/backend/manifest.py b/src/govoplan_connectors/backend/manifest.py index d153cfe..319e8c4 100644 --- a/src/govoplan_connectors/backend/manifest.py +++ b/src/govoplan_connectors/backend/manifest.py @@ -71,6 +71,7 @@ TABULAR_SOURCE_INTERFACE_VERSION = "0.1.0" DATASOURCE_ORIGIN_INTERFACE_VERSION = "0.1.0" SANCTIONS_SNAPSHOT_INTERFACE_VERSION = "1.0.0" FEED_INTERFACE_VERSION = "0.1.0" +CONNECTOR_RUNTIME_INTERFACE_VERSION = "1.0.0" ARCHITECTURE = ModuleArchitectureDeclaration( layer="data_reporting_integration", @@ -358,6 +359,10 @@ manifest = ModuleManifest( name="connectors.feeds", version=FEED_INTERFACE_VERSION, ), + ModuleInterfaceProvider( + name="connectors.runtime_contract", + version=CONNECTOR_RUNTIME_INTERFACE_VERSION, + ), ), permissions=PERMISSIONS, role_templates=ROLE_TEMPLATES, @@ -424,6 +429,22 @@ manifest = ModuleManifest( related_modules=("datasources", "dataflow", "ops", "policy", "audit"), order=39, ), + DocumentationTopic( + id="connectors.runtime-preview-contract", + title="Connector previews and diagnostics", + summary="Use one bounded, redacted dry-run shape across external transports.", + body=( + "Connectors owns endpoint discovery, authentication hand-off, transport limits, retries, and protocol health. " + "Domain modules own field mapping, validation, reconciliation, and record mutation. The shared Core runtime " + "contract reports redacted effects and diagnostics with source revisions, fingerprints, and immutable input hashes. " + "A commit must reject stale, truncated, conflicting, or error-bearing previews, and credentials never appear in URLs or samples." + ), + layer="available", + documentation_types=("admin", "user"), + audience=("operator", "module_admin", "power_user"), + related_modules=("addresses", "datasources", "dataflow", "policy", "audit"), + order=40, + ), DocumentationTopic( id="connectors.tabular-sources", title="Governed tabular sources",