Coming soon · Contract draft

Staffing & Capacity

Planned

A people-demand-allocation graph with proposals separated from confirmed assignments and financial fields separately scoped.

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

Staffing, capacity, role, and assignment services

Contract posture

P1 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Work/Finance + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 3 · Resource Management

Contract dependencies

• Financial/privacy scope matrix
• Generic Operation resource
• Transactional audit and event contracts

What this unlocks

Integrate staffing demand

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

Compare capacity options

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

Confirm assignments safely

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

Lifecycle and invariants

Staffing & Capacity exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftopenproposedconfirmedfilledcancelled

From	To	Command	Authority
draft	open	Open request	Staffing and assignment services
open	proposed	Propose assignment	Staffing and assignment services
proposed	confirmed	Confirm assignment	Staffing and assignment services
confirmed	filled	Fill request	Staffing and assignment services

Lifecycle invariants

• Recommendations never become assignments automatically.
• Rates and margin remain under financial scopes.

Authority boundaries

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

DigitalStack owns

• Staffing request and role demand
• Capacity and availability model
• Assignment proposal and confirmation lifecycle

Explicitly not building

• Recommendations becoming assignments automatically
• Rate or margin access through staffing scopes
• External planners owning DigitalStack allocation truth

Surface decisions

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

add

Requests, roles, capacity, recommendations, assignment proposals, and confirmations

Integrations need the complete demand-to-allocation workflow.

keep

Proposal and confirmation as separate commands

Resource planning advice must not gain staffing authority.

remove

Silent assignment and rate/margin fields from staffing scopes

These violate human authority and financial separation.

Interface plan

REST API

Planned

Versioned staffing & capacity resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable StaffingRequest 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 staffing request lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Runn / HRIS / PSA 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 /staffing/requests	staffingRequest(id: ID!): StaffingRequest	get_staffing_capacity	—	Staffing, capacity, role, and assignment services
Primary command	POST /staffing/requests	draftStaffingRequestChange(input: DraftStaffingRequestChangeInput!): StaffingRequestChangeProposal!	draft_staffing_capacity_change	staffing_request.created	Staffing, capacity, role, and assignment services

Scopes

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

staffing:readexisting scope · planned expansion

Read governed staffing & capacity resources.

staffing:writeplanned scope

Create and edit bounded staffing & capacity fields.

staffing:operateplanned scope

Run explicit staffing & capacity lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Staffing, capacity, role, and assignment 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/staffing/requests

List staffing & capacity

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

staffing:read

POST/api/v1/staffing/requestsconfirmation

Create StaffingRequest

Create one canonical resource with idempotency and actor attribution.

staffing:write

GET/api/v1/staffing/requests/{id}

Retrieve StaffingRequest

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

staffing:read

PATCH/api/v1/staffing/requests/{id}confirmation

Update StaffingRequest

Update bounded editable fields using optimistic versioning.

staffing:write

POST/api/v1/staffing/requests/{id}/confirm-assignmentconfirmation

confirm assignment StaffingRequest

Run one explicit domain command after validation and authorization.

staffing:operate

confirm assignment a StaffingRequest

Planned request

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

Planned response

{
  "data": {
    "id": "staffing_request_123",
    "status": "assignment_confirmed",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

StaffingRequest

StaffingRequestConnection

StaffingRequestChangeProposal

Operation

Queries

staffingRequest(id: ID!): StaffingRequest

staffingRequestList(filter: StaffingRequestFilter, pagination: PaginationInput): StaffingRequestConnection!

Mutations

draftStaffingRequestChange(input: DraftStaffingRequestChangeInput!): StaffingRequestChangeProposal!

applyStaffingRequestChange(input: ApplyStaffingRequestChangeInput!): StaffingRequestPayload!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Staffing & Capacity

get_staffing_capacity

Planned

Read the authorized staffing & capacity state, provenance, and allowed actions.

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

Draft Staffing & Capacity change

draft_staffing_capacity_change

Planned

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

Scope: staffing: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 Staffing & Capacity change

apply_staffing_capacity_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: staffing: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 staffing & capacity change and help me apply it.

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

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

staffing_request.createdplanned event

A canonical StaffingRequest was created.

payload: staffing_request_id, status, created_at

staffing_request.updatedplanned event

Governed StaffingRequest fields changed.

payload: staffing_request_id, changed_fields, version, occurred_at

staffing_request.assignment_confirmedplanned event

The confirm assignment command completed.

payload: staffing_request_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded staffing & capacity proposals through MCP.

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

Runn / HRIS / PSA

Synchronization provider

Exchange people, availability, demand, and approved allocations.

Authority: Field direction, timing, conflict policy, and financial visibility are declared per provider.

Open contract decisions

Resolve before implementation approval

• Which assignment changes require approval from both delivery and people management?

Proof obligations

Must remain true	Failure indicator
Staffing, capacity, role, and assignment 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.