Coming soon · Contract draft

Delivery Health & Recovery

Planned

A delivery intelligence contract for health snapshots, forecast settings, recovery proposals, and human decisions.

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

Delivery health, forecast, and recovery 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

Explain health change

Read a stable domain model for delivery health & recovery without depending on GUI routes or database shapes.

Compare forecast history

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

Review recovery proposals

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

Lifecycle and invariants

Delivery Health & Recovery exposes a bounded lifecycle with explicit commands and named authority at every transition.

healthywatchat_riskrecoveringrecovered

From	To	Command	Authority
healthy	watch	Record warning	Delivery health and recovery services
watch	at_risk	Cross risk threshold	Delivery health and recovery services
at_risk	recovering	Accept recovery plan	Delivery health and recovery services
recovering	recovered	Confirm recovery	Delivery health and recovery services

Lifecycle invariants

• Health state is evidence-backed and versioned.
• Recovery proposals never move schedules until governed commands apply.

Authority boundaries

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

DigitalStack owns

• Health snapshot definitions
• Forecast and burn projections
• Recovery proposal and decision lifecycle

Explicitly not building

• Advisory health mutating schedules
• Opaque model output without evidence
• Automatic acceptance of recovery plans

Surface decisions

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

add

Health history, forecast settings, recovery proposals, and named decisions

Consumers need change over time and explicit response workflows.

keep

Existing health reads and evidence explanations

They are valuable advisory foundations.

remove

Generic create/update of health snapshots and automatic recovery application

Snapshots are service-generated facts; agents do not author health truth.

add

Project/engagement-scoped filtering on every read and command

A workspace API key is not a licence to read every project. Access composes workspace membership with per-project visibility, so integrators receive exactly the engagements they are entitled to.

Interface plan

REST API

Planned

Versioned delivery health & recovery resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

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

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and human-request tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense delivery health lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Slack / Teams / analytics 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 /delivery/health	deliveryHealth(id: ID!): DeliveryHealth	get_delivery_health_recovery	—	Delivery health, forecast, and recovery services
Primary command	POST /delivery/health/{id}/accept-recovery	draftDeliveryHealthChange(input: DraftDeliveryHealthChangeInput!): DeliveryHealthChangeProposal!	draft_delivery_health_recovery_change	delivery_health.created	Delivery health, forecast, and recovery services

Proposed scopes

Proposed scopes are not grantable yet.

delivery-health:readplanned scope

Read governed delivery health & recovery resources.

delivery-health:writeplanned scope

Create and edit bounded delivery health & recovery fields.

delivery-health:operateplanned scope

Run explicit delivery health & recovery lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Project / engagement-scoped access

A project and its engagement are the same object here. Resources are scoped to the projects the principal can access: workspace membership plus project-level visibility — owners and admins see every project, other principals see only the projects they created, were role-assigned, or were added to as members. List endpoints return only visible projects’ resources; detail endpoints enforce that visibility before returning or changing anything.

Canonical delegation

Every interface delegates to Delivery health, forecast, and recovery 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/delivery/health

List delivery health & recovery

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

delivery-health:read

GET/api/v1/delivery/health/{id}

Retrieve DeliveryHealth

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

delivery-health:read

POST/api/v1/delivery/health/{id}/accept-recoveryconfirmation

accept recovery DeliveryHealth

Run one explicit domain command after validation and authorization.

delivery-health:operate

GET/api/v1/delivery/health/{id}/history

Get health history

Return versioned health and forecast changes with evidence.

delivery-health:read

Execution: Synchronous

GET/api/v1/delivery/recovery-proposals

List recovery proposals

Return reviewable recovery proposals and decision state.

delivery-health:read

Execution: Synchronous

accept recovery a DeliveryHealth

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/delivery/health/delivery_health_123/accept-recovery \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: delivery-health-recovery-accept-recovery-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "delivery_health_123",
    "status": "recovery_accepted",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

DeliveryHealth

DeliveryHealthConnection

DeliveryHealthChangeProposal

Operation

Queries

deliveryHealth(id: ID!): DeliveryHealth

deliveryHealthList(filter: DeliveryHealthFilter, pagination: PaginationInput): DeliveryHealthConnection!

Mutations

draftDeliveryHealthChange(input: DraftDeliveryHealthChangeInput!): DeliveryHealthChangeProposal!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Delivery Health & Recovery

get_delivery_health_recovery

Planned

Read the authorized delivery health & recovery state, provenance, and allowed actions.

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

Draft Delivery Health & Recovery change

draft_delivery_health_recovery_change

Planned

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

Scope: delivery-health: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.

Request Delivery Health & Recovery action

request_delivery_health_recovery_action

Planned

Prepare an authorized human action request without executing the high-risk command.

Scope: delivery-health:operate
Input: Proposal id, expected version, named decision maker, and reason.
Output: A pending human-action request and audit reference.
Write boundary: The agent cannot execute the final command.

Planned agent workflow

User: Review the proposed delivery health & recovery change and help me apply it.

1. Call get_delivery_health_recovery to inspect current state, provenance, and allowed actions.
2. Call draft_delivery_health_recovery_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. Call request_delivery_health_recovery_action so an authorized human can decide.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

delivery_health.createdplanned event

A canonical DeliveryHealth was created.

payload: delivery_health_id, status, created_at

delivery_health.updatedplanned event

Governed DeliveryHealth fields changed.

payload: delivery_health_id, changed_fields, version, occurred_at

delivery_health.recovery_acceptedplanned event

The accept recovery command completed.

payload: delivery_health_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded delivery health & recovery proposals through MCP.

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

Slack / Teams / analytics

Action sink

Deliver threshold alerts and reviewed recovery requests.

Authority: Alerts and responses delegate to canonical decision authority.

Open contract decisions

Resolve before implementation approval

• Which forecast-setting changes belong to direct configuration versus governed recovery decisions?

Proof obligations

Must remain true	Failure indicator
Delivery health, forecast, and recovery 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.