govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md

External References And Integration Maturity

GovOPlaN integrations use a shared external-reference contract instead of storing connector-specific URLs and identifiers in every module.

An external reference identifies an object by:

• external system instance
• object type
• stable external object ID
• optional connector configuration
• canonical HTTP(S) URL without embedded credentials
• optional source version, ETag, observation time, and non-secret metadata

The identity key is system:object_type:object_id. A GovOPlaN object may retain multiple references, but one reference must never silently change its identity. Moving or escalating work creates a new object and an explicit relationship; it does not rewrite either object's history.

Integration Maturity

Maturity is cumulative:

1. discover: identify configured external systems and their health.
2. link: retain and open stable external references.
3. search: include authorized external objects in GovOPlaN search.
4. read: display authoritative external content.
5. publish: create or update external content from GovOPlaN.
6. synchronize: reconcile changes in both directions with conflict handling.
7. migrate: perform a governed, verifiable transfer into GovOPlaN.
8. replace: provide the native operational capability without the external tool.

Connectors must declare and document the maturity they actually implement. synchronize requires durable cursors, idempotency, provenance, conflict handling, deletion semantics, and observable failures. A link-only connector must not imply that GovOPlaN holds an authoritative copy.

Source Authority Is A Separate Dimension

Integration maturity states what an adapter is capable of doing. It does not decide which system owns truth for a configured object or field group. A binding separately selects one of the source-authority modes defined by the institutional governance target architecture:

• native_authoritative
• external_authoritative
• external_mirror
• governed_sync
• governance_overlay
• linked_reference

A connector can therefore support synchronize while a tenant deliberately uses it only as an external mirror. Conversely, a native GovOPlaN object may retain link-only references to several external systems. Authority may be narrowed by tenant, organization, service, object type, object, field group, or process step and must be visible in provenance and configuration preflight.

Domain Ownership

• Domain modules own native GovOPlaN objects and their authorization.
• Connectors own protocols, credentials, discovery, transport, and sync state.
• Search owns indexing and result aggregation, but source modules remain responsible for authorization.
• Core owns only the stable DTOs and extension contracts.

The Python contract is govoplan_core.core.external_references.ExternalObjectReference.