Coming soon · Contract draft

Risk Intelligence

Planned

A risk-intelligence contract for scored delivery risks, evidence, trend explanations, thresholds, mitigation drafts, and reviewable 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

Risk intelligence, dependency, blocker, and mitigation 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 · Risk intelligence

Contract dependencies

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

What this unlocks

Explain risk movement

Read a stable domain model for risk intelligence without depending on GUI routes or database shapes.

Draft mitigation proposals

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

Subscribe to risk thresholds

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

Lifecycle and invariants

Risk Intelligence exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftreviewapprovedpublishedsuperseded

From	To	Command	Authority
draft	review	Review Risk Intelligence	Risk intelligence, dependency, blocker, and mitigation services
review	approved	Approve Risk Intelligence	Risk intelligence, dependency, blocker, and mitigation services
approved	published	Publish Risk Intelligence	Risk intelligence, dependency, blocker, and mitigation services
published	superseded	Supersede Risk Intelligence	Risk intelligence, dependency, blocker, and mitigation services

Lifecycle invariants

• Risk scores and narratives include evidence references.
• This is a read surface: mitigation proposals are read here but only resolved through the separate Risks, Dependencies & Blockers command capability.

Authority boundaries

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

DigitalStack owns

• Risk score and narrative definitions
• Evidence and contributing-signal attribution
• Mitigation proposal lifecycle

Explicitly not building

• Risk scores resolving source issues automatically
• Opaque risk narratives without evidence
• External trackers replacing DigitalStack risk identity

Surface decisions

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

add

Risk Intelligence REST, GraphQL, MCP, webhook, and connected-app surfaces

The capability should return to the live Capabilities section only when every advertised interface has a backed runtime contract.

keep

Risk Intelligence as documentation-first until runtime parity exists

Partial runtime slices should not appear as a fully available customer capability.

remove

Claims that Risk Intelligence is available before REST, GraphQL, MCP, and webhooks are implemented

The developer docs must not make customers infer support that does not exist yet.

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 risk intelligence resources, commands, idempotency, and operation status.

Read only

GraphQL

Planned

Composable, read-only risk intelligence discovery through the canonical service.

Read only · no customer mutations

MCP / Agent API

Planned

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

Read only

Webhooks

Planned

Past-tense risk intelligence lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Issue trackers / Slack / Teams / email 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 /risk-intelligence	riskIntelligence(id: ID!): RiskIntelligence	get_risk_intelligence	—	Risk intelligence, dependency, blocker, and mitigation services
Primary command	Not exposed	Not exposed	Not exposed	risk_intelligence.created	Risk intelligence, dependency, blocker, and mitigation services

Proposed scopes

Proposed scopes are not grantable yet.

risk-intelligence:readplanned scope

Read governed risk scores, narratives, contributing evidence, and mitigation proposals. This is an advisory read surface — it exposes no write or operate scope.

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 Risk intelligence, dependency, blocker, and mitigation 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.

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/risk-intelligence

List risk intelligence

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

risk-intelligence:read

GET/api/v1/risk-intelligence/{id}

Retrieve RiskIntelligence

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

risk-intelligence:read

GET/api/v1/projects/{id}/risk-intelligence

Get project risk intelligence

Return current risk scores, narratives, and contributing evidence for one visible project.

risk-intelligence:read

Execution: Synchronous

GET/api/v1/risk-intelligence/mitigations

List mitigation proposals

Return advisory mitigation proposals across the projects the caller can access.

risk-intelligence:read

Execution: Synchronous

List risk intelligence

Planned request

curl --request GET \
  --url "https://www.digitalstack360.com/api/v1/risk-intelligence" \
  --header "Authorization: Bearer $DSTACK_API_KEY"

Planned response

{
  "data": [
    {
      "id": "risk-intelligence_123",
      "status": "available",
      "version": 1
    }
  ]
}

GraphQL

Proposed graph

Planned

Types

RiskIntelligence

RiskIntelligenceConnection

RiskIntelligenceChangeProposal

Operation

Queries

riskIntelligence(id: ID!): RiskIntelligence

riskIntelligenceList(filter: RiskIntelligenceFilter, pagination: PaginationInput): RiskIntelligenceConnection!

No GraphQL mutations planned

Read only. Customer callers cannot create, edit, publish, or administer these DigitalStack-owned resources.

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Risk Intelligence

get_risk_intelligence

Planned

Read the authorized risk intelligence state, provenance, and allowed actions.

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

Planned agent workflow

User: Explain the current risk intelligence for a project I can access.

1. Call get_risk_intelligence to read the authorized state, contributing evidence, and provenance.
2. Summarize the facts and their evidence for the user.

This is a read-only surface: there is no draft, apply, or command tool to call.

Webhooks

Proposed event catalog

Planned

Event types

risk_intelligence.createdplanned event

A canonical RiskIntelligence was created.

payload: risk_intelligence_id, status, created_at

risk_intelligence.updatedplanned event

Governed RiskIntelligence fields changed.

payload: risk_intelligence_id, changed_fields, version, occurred_at

risk_intelligence.triagedplanned event

The triage command completed.

payload: risk_intelligence_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded risk intelligence proposals through MCP.

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

Issue trackers / Slack / Teams / email

Source connector

Supply risk evidence and escalation context.

Authority: Evidence informs risk intelligence; resolution remains an explicit domain command.

Open contract decisions

Resolve before implementation approval

• Which risk categories need separate scopes before public release?

Proof obligations

Must remain true	Failure indicator
Risk intelligence, dependency, blocker, and mitigation 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.