Coming soon · Contract draft

Commitments & vSOW

Planned

A commitment-and-vSOW contract for delivery promises, package versions, acceptance evidence, amendments, publication, and customer approval authority.

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

Commitment, acceptance, vSOW package, amendment, and signature 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 · Commercial-delivery authority

Contract dependencies

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

What this unlocks

Trace commitments to vSOW scope

Read a stable domain model for commitments & vsow without depending on GUI routes or database shapes.

Coordinate acceptance and amendment workflows

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

Publish governed package versions

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

Lifecycle and invariants

Commitments & vSOW exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftinternal_reviewapprovedsentsignedarchived

From	To	Command	Authority
draft	internal_review	Submit package for review	Commitment, acceptance, vSOW package, amendment, and signature services
internal_review	approved	Approve package	Commitment, acceptance, vSOW package, amendment, and signature services
approved	sent	Freeze snapshot and send to customer	Commitment, acceptance, vSOW package, amendment, and signature services
sent	signed	Record customer signature	Commitment, acceptance, vSOW package, amendment, and signature services
signed	archived	Archive superseded package	Commitment, acceptance, vSOW package, amendment, and signature services

Lifecycle invariants

• A published snapshot is immutable and content-addressed — the API reads it, and never edits what was sold.
• Human acceptance and customer signature authority can never be delegated to an agent or API key.
• Commitments and their vSOW package are explicitly linked but separately owned: package state does not silently fulfil a commitment, and vice versa.
• Amendments follow proposal → human decision → application; the API creates proposals and records decisions but never self-applies a scope change.

Authority boundaries

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

DigitalStack owns

• Commitment-to-package linkage
• vSOW package and amendment lifecycle
• Acceptance and publication audit history

Explicitly not building

• Agents signing or accepting for humans
• Contract text mutation through broad project scopes
• Provider signature state silently overriding package state

Surface decisions

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

add

Package, immutable snapshot, commitment, acceptance-evidence, amendment-proposal, and signature-status resources

A real vSOW API needs the sold-scope commitment vocabulary, not a generic document CRUD.

keep

Human signature and amendment approval as the only authority for accepting scope

Connected e-signature providers transport a decision; they never own it.

remove

Agent-applied amendments, agent signatures, and edits to a frozen snapshot

These exceed both least privilege and the write-once integrity of what was sold.

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 commitments & vsow resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable CommitmentVsow 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 commitment vsow lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

DocuSign / Adobe Sign / customer portal 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 /projects/{id}/vsow-packages	commitmentVsow(id: ID!): CommitmentVsow	get_vsow_package	—	Commitment, acceptance, vSOW package, amendment, and signature services
Primary command	POST /vsow-packages/{id}/amendments	draftCommitmentVsowChange(input: DraftCommitmentVsowChangeInput!): CommitmentVsowChangeProposal!	draft_vsow_amendment	vsow_package.sent	Commitment, acceptance, vSOW package, amendment, and signature services

Proposed scopes

Proposed scopes are not grantable yet.

commitments-vsow:readplanned scope

Read vSOW packages, immutable snapshots, commitments, acceptance evidence, amendment history, and signature status for the projects/engagements the caller can access.

commitments-vsow:amendplanned scope

Create amendment proposals against a vSOW package. A proposal never changes the frozen snapshot or the package on its own.

commitments-vsow:decideplanned scope

Record a named human decision on an amendment proposal (approve/defer/reject). Customer signature and acceptance stay human-only and are never granted to an API key or agent.

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 Commitment, acceptance, vSOW package, amendment, and signature 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/projects/{id}/vsow-packages

List vSOW packages

Return the vSOW packages for one visible project/engagement with status and active snapshot.

commitments-vsow:read

Execution: Synchronous

GET/api/v1/vsow-packages/{id}

Get a vSOW package

Return one package, its live status, linked commitments, and the id of its active immutable snapshot.

commitments-vsow:read

Execution: Synchronous

GET/api/v1/vsow-packages/{id}/snapshots

List package snapshots

Return the write-once snapshots (what was sent/signed) with revision numbers and lifecycle state.

commitments-vsow:read

Execution: Synchronous

GET/api/v1/vsow-packages/{id}/commitments

List commitments

Return the package’s commitments — milestones, deliverables, acceptance and launch events — with status and target dates.

commitments-vsow:read

Execution: Synchronous

GET/api/v1/vsow-packages/{id}/signatures

Get signature status

Return the customer signature status for a package’s snapshot without exposing signature secrets.

commitments-vsow:read

Execution: Synchronous

POST/api/v1/vsow-packages/{id}/amendmentsconfirmation

Propose an amendment

Create an amendment proposal against a package. This never edits the frozen snapshot or applies the change.

commitments-vsow:amend

Execution: Synchronous
Idempotency: Required

POST/api/v1/vsow-amendments/{id}/decisionconfirmation

Record an amendment decision

Record a named human approve/defer/reject decision on an amendment proposal.

commitments-vsow:decide

Execution: Synchronous
Idempotency: Required

publish a CommitmentVsow

Planned request

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

Planned response

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

GraphQL

Proposed graph

Planned

Types

CommitmentVsow

CommitmentVsowConnection

CommitmentVsowChangeProposal

Operation

Queries

commitmentVsow(id: ID!): CommitmentVsow

commitmentVsowList(filter: CommitmentVsowFilter, pagination: PaginationInput): CommitmentVsowConnection!

Mutations

draftCommitmentVsowChange(input: DraftCommitmentVsowChangeInput!): CommitmentVsowChangeProposal!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get vSOW package

get_vsow_package

Planned

Read a package, its commitments, snapshot lineage, and signature status for a project the caller can access.

Scope: commitments-vsow:read
Input: Package id or a project filter.
Output: Package detail, commitments, and snapshot/signature state with provenance.
Write boundary: Read only.

Draft a vSOW amendment

draft_vsow_amendment

Planned

Build a reviewable amendment proposal against a package from explicit user intent and evidence.

Scope: commitments-vsow:amend
Input: Package id, requested change, and evidence references.
Output: A persisted amendment proposal and validation results.
Write boundary: Creates a proposal only — never edits the snapshot, applies the change, or signs.

Planned agent workflow

User: Review the proposed commitments & vsow change and help me apply it.

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

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

vsow_package.sentplanned event

A vSOW package snapshot was frozen and sent to the customer.

payload: vsow_package_id, snapshot_id, revision_number, sent_at

vsow_package.signedplanned event

A customer signed a vSOW package snapshot.

payload: vsow_package_id, snapshot_id, signature_reference, signed_at

vsow_commitment.fulfilledplanned event

A commitment under a package was marked fulfilled.

payload: vsow_package_id, commitment_id, commitment_kind, occurred_at

vsow_amendment.decidedplanned event

A named human recorded a decision on an amendment proposal.

payload: vsow_package_id, amendment_proposal_id, decision, decided_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "commitment_vsow.published",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "commitment_vsow",
    "id": "commitment_vsow_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "commitment_vsow_id": "commitment_vsow_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 commitments & vsow proposals through MCP.

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

DocuSign / Adobe Sign / customer portal

Action sink

Present approvals and return named signature or acceptance facts.

Authority: Named humans retain signing and acceptance authority.

Open contract decisions

Resolve before implementation approval

• Which package fields can be drafted through the amendment-proposal API before human review is required?
• Should signature-complete events carry signer identity or only an authorized reference?

Proof obligations

Must remain true	Failure indicator
Commitment, acceptance, vSOW package, amendment, and signature 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.