Coming soon · Contract draft

Provider Reflection & Sync

Planned

A provider-neutral Execute integration surface for connection health, mapping review, dry runs, conflicts, and explicit apply.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Execute provider SDK, source-reflection, and mapping services

Contract posture

P1 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Delivery/Execute + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 2 · Project and Execute core

Contract dependencies

• Canonical domain service adapter
• Optimistic concurrency and idempotency policy
• Transactional event outbox

What this unlocks

Inspect provider health

Read a stable domain model for provider reflection & sync without depending on GUI routes or database shapes.

Review mappings and drift

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Apply synchronization explicitly

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Provider Reflection & Sync exposes a bounded lifecycle with explicit commands and named authority at every transition.

disconnectedconnectedmappingreadydegradedrevoked

From	To	Command	Authority
disconnected	connected	Authorize provider	Execute provider SDK and mapping services
connected	mapping	Configure mappings	Execute provider SDK and mapping services
mapping	ready	Approve mapping	Execute provider SDK and mapping services
ready	degraded	Detect source drift	Execute provider SDK and mapping services
degraded	revoked	Revoke connection	Execute provider SDK and mapping services

Lifecycle invariants

• One Jira provider authority exists.
• Dry run and apply remain separate and provenance-bearing.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• Connection and mapping lifecycle
• Source reflection and provenance
• Sync conflict and run history

Explicitly not building

• Hidden provider-specific canonical fields
• Automatic conflict resolution
• A second Jira integration authority

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Connection status, mappings, reflection, conflicts, drift, and dry-run resources

Provider integrations need a common operational model.

keep

Jira as the first normalized provider

The real foundation should become the canonical Jira story.

remove

Second Jira integration entries and hidden conflict apply

Duplicate authorities and automatic resolution would institutionalize drift.

Interface plan

REST API

Planned

Versioned provider reflection & sync resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable ExecuteProvider reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and confirmed apply tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense provider sync lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Jira / GitHub / Azure DevOps / Linear plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /execute/providers	executeProvider(id: ID!): ExecuteProvider	get_provider_reflection	—	Execute provider SDK, source-reflection, and mapping services
Primary command	POST /execute/providers	draftExecuteProviderChange(input: DraftExecuteProviderChangeInput!): ExecuteProviderChangeProposal!	draft_provider_reflection_change	provider_sync.created	Execute provider SDK, source-reflection, and mapping services

Proposed scopes

Proposed scopes are not grantable yet.

execute-providers:readplanned scope

Read governed provider reflection & sync resources.

execute-providers:writeplanned scope

Create and edit bounded provider reflection & sync fields.

execute-providers:operateplanned scope

Run explicit provider reflection & sync lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Execute provider SDK, source-reflection, and mapping services; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/execute/providers

List provider reflection & sync

Return an authorized, paginated collection with stable filters and provenance.

execute-providers:read

POST/api/v1/execute/providersconfirmation

Create ExecuteProvider

Create one canonical resource with idempotency and actor attribution.

execute-providers:write

GET/api/v1/execute/providers/{id}

Retrieve ExecuteProvider

Return canonical detail, lifecycle state, permissions, and allowed actions.

execute-providers:read

PATCH/api/v1/execute/providers/{id}confirmation

Update ExecuteProvider

Update bounded editable fields using optimistic versioning.

execute-providers:write

POST/api/v1/execute/providers/{id}/run-dry-runconfirmation

run dry run ExecuteProvider

Run one explicit domain command after validation and authorization.

execute-providers:operate

run dry run a ExecuteProvider

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/execute/providers/provider_sync_123/run-dry-run \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: provider-reflection-run-dry-run-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "provider_sync_123",
    "status": "validated",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

ExecuteProvider

ExecuteProviderConnection

ExecuteProviderChangeProposal

Operation

Queries

executeProvider(id: ID!): ExecuteProvider

executeProviderList(filter: ExecuteProviderFilter, pagination: PaginationInput): ExecuteProviderConnection!

Mutations

draftExecuteProviderChange(input: DraftExecuteProviderChangeInput!): ExecuteProviderChangeProposal!

applyExecuteProviderChange(input: ApplyExecuteProviderChangeInput!): ExecuteProviderPayload!

Planned GraphQL query

query ExecuteProviderDetail($id: ID!) {
  executeProvider(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Provider Reflection & Sync

get_provider_reflection

Planned

Read the authorized provider reflection & sync state, provenance, and allowed actions.

Scope: execute-providers:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Draft Provider Reflection & Sync change

draft_provider_reflection_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: execute-providers:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Apply Provider Reflection & Sync change

apply_provider_reflection_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: execute-providers:operate
Input: Proposal id, expected version, idempotency key, and explicit confirmation.
Output: Updated canonical resource and audit reference.
Write boundary: Confirmation, optimistic versioning, and idempotency required.

Planned agent workflow

User: Review the proposed provider reflection & sync change and help me apply it.

1. Call get_provider_reflection to inspect current state, provenance, and allowed actions.
2. Call draft_provider_reflection_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. After explicit confirmation, call apply_provider_reflection_change with the proposal version.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

provider_sync.createdplanned event

A canonical ExecuteProvider was created.

payload: provider_sync_id, status, created_at

provider_sync.updatedplanned event

Governed ExecuteProvider fields changed.

payload: provider_sync_id, changed_fields, version, occurred_at

provider_sync.validatedplanned event

The run dry run command completed.

payload: provider_sync_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "provider_sync.validated",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "provider_sync",
    "id": "provider_sync_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "provider_sync_id": "provider_sync_123",
    "prior_status": "draft",
    "status": "validated"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded provider reflection & sync proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Jira / GitHub / Azure DevOps / Linear

Synchronization provider

Reflect provider work through normalized mappings.

Authority: Direction, field authority, conflict policy, and writeback are explicit per connection.

Open contract decisions

Resolve before implementation approval

• Which fields, if any, become bidirectional in the first provider release?

Proof obligations

Must remain true	Failure indicator
Execute provider SDK, source-reflection, and mapping services remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.