Coming soon · Contract draft

Adoption, Imports & Mappings

Planned

A lineage-first adoption contract from source credentials through raw, normalized, mapped, and canonical records.

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

Adoption workspace, ingestion, topology, mapping, and reconciliation services

Contract posture

P2 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Commercial/Knowledge + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 6 · Knowledge and intake

Contract dependencies

• Canonical identity and provider mapping policy
• Field-level visibility rules
• Transactional event outbox

What this unlocks

Operate imports safely

Read a stable domain model for adoption, imports & mappings without depending on GUI routes or database shapes.

Trace source lineage

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

Review mappings and drift

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

Lifecycle and invariants

Adoption, Imports & Mappings exposes a bounded lifecycle with explicit commands and named authority at every transition.

configuredingestinganalyzedmapping_proposedapprovedappliedreconciliation_required

From	To	Command	Authority
configured	ingesting	Start import	Adoption and canonical mapping services
ingesting	analyzed	Analyze source	Adoption and canonical mapping services
analyzed	mapping_proposed	Propose mapping	Adoption and canonical mapping services
mapping_proposed	approved	Approve mapping	Adoption and canonical mapping services
approved	applied	Apply mapping	Adoption and canonical mapping services

Lifecycle invariants

• Raw-to-canonical lineage is immutable.
• Proposal and apply remain separate.

Authority boundaries

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

DigitalStack owns

• Adoption run and source inventory
• Raw-to-normalized-to-canonical lineage
• Mapping proposal, review, and apply lifecycle

Explicitly not building

• Mapping proposals applying themselves
• Raw credentials or source secrets in APIs
• A second Jira authority outside provider services

Surface decisions

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

add

Workspace, run, source inventory, delta, lineage, mapping, drift, and reconciliation resources

Operators need to see how source data becomes canonical.

keep

Jira as the first adoption provider with one canonical provider story

The working ingestion foundation should not compete with a placeholder extension.

remove

Credential retrieval, automatic mapping apply, and duplicate provider authorities

These create security and legitimacy failures.

Interface plan

REST API

Planned

Versioned adoption, imports & mappings resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable AdoptionRun 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 adoption run lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Jira / ADO / Linear / GitHub / CSV 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 /adoption/runs	adoptionRun(id: ID!): AdoptionRun	get_adoption_imports	—	Adoption workspace, ingestion, topology, mapping, and reconciliation services
Primary command	POST /adoption/runs	draftAdoptionRunChange(input: DraftAdoptionRunChangeInput!): AdoptionRunChangeProposal!	draft_adoption_imports_change	adoption_run.created	Adoption workspace, ingestion, topology, mapping, and reconciliation services

Proposed scopes

Proposed scopes are not grantable yet.

adoption:readplanned scope

Read governed adoption, imports & mappings resources.

adoption:writeplanned scope

Create and edit bounded adoption, imports & mappings fields.

adoption:operateplanned scope

Run explicit adoption, imports & mappings lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Adoption workspace, ingestion, topology, mapping, and reconciliation 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/adoption/runs

List adoption, imports & mappings

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

adoption:read

POST/api/v1/adoption/runsconfirmation

Create AdoptionRun

Create one canonical resource with idempotency and actor attribution.

adoption:write

GET/api/v1/adoption/runs/{id}

Retrieve AdoptionRun

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

adoption:read

PATCH/api/v1/adoption/runs/{id}confirmation

Update AdoptionRun

Update bounded editable fields using optimistic versioning.

adoption:write

POST/api/v1/adoption/runs/{id}/apply-mappingconfirmation

apply mapping AdoptionRun

Run one explicit domain command after validation and authorization.

adoption:operate

apply mapping a AdoptionRun

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/adoption/runs/adoption_run_123/apply-mapping \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: adoption-imports-apply-mapping-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "adoption_run_123",
    "status": "mapping_applied",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

AdoptionRun

AdoptionRunConnection

AdoptionRunChangeProposal

Operation

Queries

adoptionRun(id: ID!): AdoptionRun

adoptionRunList(filter: AdoptionRunFilter, pagination: PaginationInput): AdoptionRunConnection!

Mutations

draftAdoptionRunChange(input: DraftAdoptionRunChangeInput!): AdoptionRunChangeProposal!

applyAdoptionRunChange(input: ApplyAdoptionRunChangeInput!): AdoptionRunPayload!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Adoption, Imports & Mappings

get_adoption_imports

Planned

Read the authorized adoption, imports & mappings state, provenance, and allowed actions.

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

Draft Adoption, Imports & Mappings change

draft_adoption_imports_change

Planned

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

Scope: adoption: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 Adoption, Imports & Mappings change

apply_adoption_imports_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: adoption: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 adoption, imports & mappings change and help me apply it.

1. Call get_adoption_imports to inspect current state, provenance, and allowed actions.
2. Call draft_adoption_imports_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_adoption_imports_change with the proposal version.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

adoption_run.createdplanned event

A canonical AdoptionRun was created.

payload: adoption_run_id, status, created_at

adoption_run.updatedplanned event

Governed AdoptionRun fields changed.

payload: adoption_run_id, changed_fields, version, occurred_at

adoption_run.mapping_appliedplanned event

The apply mapping command completed.

payload: adoption_run_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded adoption, imports & mappings proposals through MCP.

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

Jira / ADO / Linear / GitHub / CSV

Source connector

Supply source records for normalized adoption and reconciliation.

Authority: Source identity and lineage are immutable; canonical apply remains explicit.

Open contract decisions

Resolve before implementation approval

• Which mapping classes are safe for batch approval?

Proof obligations

Must remain true	Failure indicator
Adoption workspace, ingestion, topology, mapping, and reconciliation 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.