Coming soon · Contract draft

Documents & Workflow Expansion

Planned

A truthful expansion contract around the existing REST and GraphQL document foundation, with publication and events versioned together.

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

DStack document, content, comment, workflow, and export services

Contract posture

P1 · 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 0–6 · Existing surface expansion

Contract dependencies

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

What this unlocks

Complete the document API

Read a stable domain model for documents & workflow expansion without depending on GUI routes or database shapes.

Publish the GraphQL schema

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

Connect review workflows

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

Lifecycle and invariants

Documents & Workflow Expansion exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftin_reviewapprovedpublishedarchivedsuperseded

From	To	Command	Authority
draft	in_review	Request review	DStack document and workflow services
in_review	approved	Approve document	DStack document and workflow services
approved	published	Publish document	DStack document and workflow services
published	archived	Archive document	DStack document and workflow services

Lifecycle invariants

• Existing live and preview status remains truthful per interface.
• Events omit content bodies by default.

Authority boundaries

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

DigitalStack owns

• Document/content/version identity
• Workflow, comment, and suggestion lifecycle
• Export and package operation state

Explicitly not building

• Claiming preview paths are generally available
• Provider file IDs as canonical document IDs
• Emitting content bodies in webhooks by default

Surface decisions

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

add

Stable assets, content, comments, search, versions, packages, signature, and MCP review workflows

The existing surface is strong but incomplete as a whole document platform.

keep

Live REST foundations and preview GraphQL with explicit status labels

Customers should know exactly which runtime paths exist today.

remove

Preview-as-available claims and content bodies in default events

Polished documentation must not overstate runtime or leak document data.

Interface plan

REST API

Planned

Versioned documents & workflow expansion resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable Document 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 document lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Drive / SharePoint / Box / DocuSign 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 /documents	document(id: ID!): Document	get_documents_workflow	—	DStack document, content, comment, workflow, and export services
Primary command	POST /documents	draftDocumentChange(input: DraftDocumentChangeInput!): DocumentChangeProposal!	draft_documents_workflow_change	document.created	DStack document, content, comment, workflow, and export services

Scopes

Existing scopes are grantable for the operations marked callable; planned scopes are not grantable yet.

documents:readexisting scope · planned expansion

Read governed documents & workflow expansion resources.

documents:writeexisting scope · planned expansion

Create and edit bounded documents & workflow expansion fields.

documents:operateplanned scope

Run explicit documents & workflow expansion lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to DStack document, content, comment, workflow, and export 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/documents

List documents & workflow expansion

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

documents:read

POST/api/v1/documentsconfirmation

Create Document

Create one canonical resource with idempotency and actor attribution.

documents:write

GET/api/v1/documents/{id}

Retrieve Document

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

documents:read

PATCH/api/v1/documents/{id}confirmation

Update Document

Update bounded editable fields using optimistic versioning.

documents:write

POST/api/v1/documents/{id}/publishconfirmation

publish Document

Run one explicit domain command after validation and authorization.

documents:operate

publish a Document

Planned request

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

Planned response

{
  "data": {
    "id": "document_123",
    "status": "published",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

Document

DocumentConnection

DocumentChangeProposal

Operation

Queries

document(id: ID!): Document

documentList(filter: DocumentFilter, pagination: PaginationInput): DocumentConnection!

Mutations

draftDocumentChange(input: DraftDocumentChangeInput!): DocumentChangeProposal!

applyDocumentChange(input: ApplyDocumentChangeInput!): DocumentPayload!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Documents & Workflow Expansion

get_documents_workflow

Planned

Read the authorized documents & workflow expansion state, provenance, and allowed actions.

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

Draft Documents & Workflow Expansion change

draft_documents_workflow_change

Planned

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

Scope: documents: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 Documents & Workflow Expansion change

apply_documents_workflow_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: documents: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 documents & workflow expansion change and help me apply it.

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

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

document.createdplanned event

A canonical Document was created.

payload: document_id, status, created_at

document.updatedplanned event

Governed Document fields changed.

payload: document_id, changed_fields, version, occurred_at

document.publishedplanned event

The publish command completed.

payload: document_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded documents & workflow expansion proposals through MCP.

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

Drive / SharePoint / Box / DocuSign

Synchronization provider

Import, export, review, or sign governed documents.

Authority: Direction and field ownership are declared per connection; secrets and share tokens remain excluded.

Open contract decisions

Resolve before implementation approval

• When should the existing GraphQL preview receive an explicit versioned public path?

Proof obligations

Must remain true	Failure indicator
DStack document, content, comment, workflow, and export 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.