feat: declare governed external provider state

docs/CONCEPT.md

@@ -11,6 +11,13 @@ results, credential references, and generic integration events. Protocol-heavy
 or domain-heavy integrations may live in dedicated modules once their scope is
 clear.
 
+Connector capability is not source ownership. Each configured binding also
+declares whether GovOPlaN is authoritative, the external system is
+authoritative, GovOPlaN keeps a mirror, both sides use governed synchronization,
+GovOPlaN supplies only a governance overlay, or the object is link-only. The
+same connector may be configured differently by tenant, service, object type,
+or field group.
+
 Detailed follow-up documents:
 
 - [Public-sector integration catalogue](PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md)
@@ -29,6 +36,8 @@ The module owns:
 - connector health status and last-test evidence
 - operator-visible integration inventory
 - cross-module discovery of available external capabilities
+- supported integration maturity, source-authority modes, operation limits,
+  and effect/reconciliation behavior for each connector type
 
 The module does not own:
 
@@ -61,6 +70,9 @@ The module should integrate through:
 - module manifest metadata, route factories, permissions, and migrations
 - a connector catalogue API for listing available connector types
 - a connection profile API with secret references, not plaintext secrets
+- a provider declaration that composes authority mode, maturity, supported
+  operations, revisions/freshness, health, limits, idempotency, conflicts,
+  evidence, and reconciliation behavior
 - capability declarations such as `connectors.catalog`,
   `connectors.profileTester`, and `connectors.health`
 - events such as `connector.profile_created`, `connector.test_succeeded`,
@@ -113,6 +125,7 @@ The first implementation should provide:
 - WebUI catalogue and profile pages
 - configuration-package fragment support
 - generic external-reference DTOs
+- source-authority binding and provider-operation metadata
 - health summary provider
 
 ## Permissions

docs/CONNECTOR_SOURCE_LIFECYCLE.md

@@ -14,6 +14,22 @@ predictable and avoids hidden module imports.
 - `bidirectional`: GovOPlaN supports both directions with conflict detection and
   reconciliation rules.
 
+Direction describes transport. Every binding also needs a source-authority
+mode:
+
+- `native_authoritative`
+- `external_authoritative`
+- `external_mirror`
+- `governed_sync`
+- `governance_overlay`
+- `linked_reference`
+
+The authority mode and the connector's integration maturity are orthogonal. A
+bidirectional connector may be configured as an external mirror, and a native
+GovOPlaN object may publish to an external target without transferring
+authority. The effective binding must identify its scope and provenance rather
+than relying on a profile-wide `sync` boolean.
+
 ## Source Data Lifecycle
 
 Connector profiles have operational states, while individual external records
@@ -103,8 +119,11 @@ this lifecycle when a connector publishes status.
    shape.
 3. Connector sends the remote request.
 4. Connector stores the remote id, version/ETag, and response diagnostics.
-5. Connector emits `connector.record_published` or `connector.publish_failed`.
-6. Domain module stores only the external-reference DTO and any domain result.
+5. A timeout or lost acknowledgement after dispatch becomes outcome-unknown,
+   not an ordinary failure or permission to duplicate the command.
+6. Connector emits a confirmed, retryable, outcome-unknown, reconciled, or
+   corrected result event.
+7. Domain module stores only the external-reference DTO and any domain result.
 
 ## Reconciliation
 
@@ -116,6 +135,25 @@ Every connector that writes to an external system needs a reconciliation story:
 - retry policy for temporary failures
 - explicit operator action for destructive overwrite or deletion
 - audit trace from GovOPlaN record to external request and response summary
+- explicit requested, approved, dispatched, possibly-executed, confirmed, and
+  reconciled/corrected effect states
+
+## Provider Declaration
+
+An executable connector type should publish machine-readable metadata for:
+
+- owned object and field groups, plus supported authority modes;
+- supported discovery, link, search, read, publish, synchronize, migrate, and
+  replacement maturity;
+- read/write/delete/preview/dry-run operations and bounded response limits;
+- revision/concurrency token, freshness, health, timeout, retry, and conflict
+  semantics;
+- idempotency and outcome-unknown handling;
+- evidence, rollback/compensation, correction, and reconciliation paths;
+- classification, purpose, retention, secret, degraded, and outage behavior.
+
+This declaration composes Core contracts. It does not move protocol behavior
+or domain semantics into Core or Connectors.
 
 ## Capability Boundary
 
@@ -158,5 +196,6 @@ Before shipping an executable connector type:
 - Add unavailable-optional-module tests for every consuming domain module.
 - Add profile test and health status fixtures.
 - Add external-reference DTO tests.
+- Add source-authority and provider-declaration validation tests.
 - Add lifecycle transition tests for pause, retry, retirement, and uninstall
   guard behavior.