Coming soon · Contract draft

Workshops & Findings

Planned

An asynchronous workshop contract for sessions, transcript assets, extraction runs, findings, synthesis, and publication.

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

Workshop session, extraction, synthesis, finding, and publication services

Contract posture

P3 · 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 6 · Knowledge and intake

Contract dependencies

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

What this unlocks

Ingest workshop evidence

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

Extract findings with provenance

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

Publish reviewed outcomes

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

Lifecycle and invariants

Workshops & Findings exposes a bounded lifecycle with explicit commands and named authority at every transition.

scheduledcapturedextractingreviewpublishedfailed

From	To	Command	Authority
scheduled	captured	Attach transcript	Workshop and finding services
captured	extracting	Start extraction	Workshop and finding services
extracting	review	Complete extraction	Workshop and finding services
review	published	Publish findings	Workshop and finding services

Lifecycle invariants

• Participant consent governs transcript access.
• Every finding retains transcript provenance.

Authority boundaries

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

DigitalStack owns

• Workshop and transcript asset identity
• Extraction run and evidence lineage
• Finding review and publication lifecycle

Explicitly not building

• Raw transcript access without participant permission
• Model findings published automatically
• Upload handled as a synchronous request

Surface decisions

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

add

Session, transcript asset, extraction Operation, finding review, synthesis, and publish resources

Uploads and model processing require an asynchronous evidence-aware workflow.

keep

Review before publication and bounded source excerpts

Findings can influence delivery only after human review.

remove

Broad raw-transcript access and automatic finding publication

These create privacy and epistemic-authority failures.

Interface plan

REST API

Planned

Versioned workshops & findings resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable Workshop 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 workshop lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Zoom / Teams / Meet 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 /workshops	workshop(id: ID!): Workshop	get_workshops_findings	—	Workshop session, extraction, synthesis, finding, and publication services
Primary command	POST /workshops	draftWorkshopChange(input: DraftWorkshopChangeInput!): WorkshopChangeProposal!	draft_workshops_findings_change	workshop.created	Workshop session, extraction, synthesis, finding, and publication services

Proposed scopes

Proposed scopes are not grantable yet.

workshops:readplanned scope

Read governed workshops & findings resources.

workshops:writeplanned scope

Create and edit bounded workshops & findings fields.

workshops:operateplanned scope

Run explicit workshops & findings lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Workshop session, extraction, synthesis, finding, and publication 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/workshops

List workshops & findings

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

workshops:read

POST/api/v1/workshopsconfirmation

Create Workshop

Create one canonical resource with idempotency and actor attribution.

workshops:write

GET/api/v1/workshops/{id}

Retrieve Workshop

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

workshops:read

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

Update Workshop

Update bounded editable fields using optimistic versioning.

workshops:write

POST/api/v1/workshops/{id}/publish-findingsconfirmation

publish findings Workshop

Run one explicit domain command after validation and authorization.

workshops:operate

publish findings a Workshop

Planned request

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

Planned response

{
  "data": {
    "id": "workshop_123",
    "status": "findings_published",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

Workshop

WorkshopConnection

WorkshopChangeProposal

Operation

Queries

workshop(id: ID!): Workshop

workshopList(filter: WorkshopFilter, pagination: PaginationInput): WorkshopConnection!

Mutations

draftWorkshopChange(input: DraftWorkshopChangeInput!): WorkshopChangeProposal!

applyWorkshopChange(input: ApplyWorkshopChangeInput!): WorkshopPayload!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Workshops & Findings

get_workshops_findings

Planned

Read the authorized workshops & findings state, provenance, and allowed actions.

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

Draft Workshops & Findings change

draft_workshops_findings_change

Planned

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

Scope: workshops: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 Workshops & Findings change

apply_workshops_findings_change

Planned

Apply a reviewed proposal through the canonical service.

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

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

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

workshop.createdplanned event

A canonical Workshop was created.

payload: workshop_id, status, created_at

workshop.updatedplanned event

Governed Workshop fields changed.

payload: workshop_id, changed_fields, version, occurred_at

workshop.findings_publishedplanned event

The publish findings command completed.

payload: workshop_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded workshops & findings proposals through MCP.

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

Zoom / Teams / Meet

Source connector

Supply authorized recording or transcript assets.

Authority: Participant consent and project access govern ingestion and visibility.

Open contract decisions

Resolve before implementation approval

• What consent evidence is required before a transcript connector may ingest a session?

Proof obligations

Must remain true	Failure indicator
Workshop session, extraction, synthesis, finding, and publication 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.