Sovereign Agent BFF — manifest & workspace fragment — OpenAPI 1.0.0

<!-- GENERATED by scripts/render-platform-map-api-docs.mjs — do not hand-edit; edit apps/agent-bff/openapi/<spec>.json and re-run. --> Scope: The published reference for Sovereign Agent BFF — manifest & workspace fragment. 142 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Sovereign Agent BFF — manifest & workspace fragment — regenerate with node scripts/render-platform-map-api-docs.mjs. See also: the OpenAPI spec index.

Servers

Tags

Paths — 142 paths / 156 operations

Operations

GET /v1/manifests

Summary: List registered manifests Description: Returns all registered manifests filtered by optional query params. Each manifest contains provider_id, organization_id, virtual_app_id, and contract_implementations. Use this to discover available services before calling resolveManifestCommunication.

Tags: manifest Operation ID: listManifests Responses:

POST /v1/manifests

Summary: Register manifest (v2 implementation_context) Description: Register or update a manifest with v2 implementation context. Creates organization, virtual app, and contract bindings. Requires governance policy compliance. Idempotent — re-registering an existing provider_id updates the manifest. Side effects: federation sync, scope advertisement, pre-verification guard check.

Tags: manifest Operation ID: registerManifest

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/manifests/{providerId}

Summary: Get manifest by provider_id Description: Retrieves a single providerId within the semantic manifest register, resolve, and federation domain

Tags: manifest Operation ID: getManifest

Parameters:

Responses:

GET /v1/manifests/{providerId}/resolved

Summary: Resolve communication binding + CNS interface Description: Processes resolved within the semantic manifest register, resolve, and federation domain

Tags: manifest Operation ID: resolveManifestCommunication

Parameters:

Responses:

GET /v1/manifests/{providerId}/input-feeds

Summary: List manifest input feed declarations (streams.input) Description: Retrieves a paginated list of input feeds within the semantic manifest register, resolve, and federation domain

Tags: manifest Operation ID: listManifestInputFeeds

Parameters:

Responses:

GET /v1/workspace/memberships

Summary: List org memberships for user Description: Retrieves a paginated list of memberships within the organization membership, virtual apps, and sovereign accounts domain

Tags: workspace Operation ID: listMemberships

Parameters:

Responses:

POST /v1/workspace/memberships

Summary: Create or update org membership Description: Creates a new memberships within the organization membership, virtual apps, and sovereign accounts domain

Tags: workspace Operation ID: createMembership Request body:

Content type: application/json

Responses:

GET /v1/workspace/virtual-apps

Summary: List virtual apps for organization Description: Retrieves a paginated list of virtual apps within the organization membership, virtual apps, and sovereign accounts domain

Tags: workspace Operation ID: listVirtualApps

Parameters:

Responses:

POST /v1/workspace/virtual-apps

Summary: Create or update organization virtual app Description: Creates a new virtual apps within the organization membership, virtual apps, and sovereign accounts domain

Tags: workspace Operation ID: createVirtualApp Request body:

Content type: application/json

Responses:

POST /v1/workspaces/org-applications

Summary: Provision organization + virtual app + manifest Description: One-call provisioning: creates org membership, sovereign account, virtual app, and registers manifest in a single transaction. Optionally creates commercial subscription and portfolio. Returns org_id, vapp_id, manifest_id. Idempotent — safe to re-call with same parameters.

Tags: workspace Operation ID: provisionOrgApplication Request body:

Content type: application/json

Responses:

POST /v1/governance/verify-interfaces

Summary: Verify manifest interfaces against governance policies Description: Validates all registered manifests for an organization against governance policies, CNS catalog, and contract compliance. Returns per-binding pass/fail with detailed issues. Use after registerManifest to confirm compliance. Also runs built-vs-approved hash gate check.

Tags: governance Operation ID: verifyInterfaces Request body:

Content type: application/json

Responses:

POST /v1/governance/verify-organization-interfaces

Summary: Verify all virtual apps for an organization implement required contracts Description: Validates and verifies verify organization interfaces within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: verifyOrganizationInterfaces Request body:

Content type: application/json

Responses:

POST /v1/fusion/traffic/enrich

Summary: Apply Google Traffic enrichment (derived output only) Description: Processes enrich within the fusion domain

Tags: fusion Operation ID: enrichTrafficFusion Request body:

Content type: application/json

Responses:

POST /v1/fusion/traffic/sensors/ingest

Summary: Ingest mock traffic sensor readings to ingest.gov.tz.traffic.sensors.* Description: Ingests ingest within the fusion domain

Tags: fusion Operation ID: ingestTrafficSensors Request body:

Content type: application/json

Responses:

POST /v1/fusion/import/plans/normalize

Summary: Normalize importer dialog payload to gov import plans feed Description: Processes normalize within the fusion domain

Tags: fusion Operation ID: normalizeImportPlans Request body:

Content type: application/json

Responses:

GET /v1/governance/policies

Summary: List active governance policies Description: Retrieves a paginated list of policies within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: listGovernancePolicies Responses:

POST /v1/governance/policies/evaluate

Summary: Evaluate applicable policies for org/vapp context Description: Evaluates evaluate within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: evaluateGovernancePolicies Request body:

Content type: application/json

Responses:

GET /v1/governance/quorum/votes

Summary: List quorum votes with attestation status for a scope Description: Retrieves a paginated list of votes within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: listQuorumVotes

Parameters:

Responses:

POST /v1/governance/quorum/votes

Summary: Query quorum votes with flexible filters Description: Processes votes within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: queryQuorumVotes Request body:

Content type: application/json

Responses:

GET /v1/governance/quorum/votes/{claimId}

Summary: Get single quorum vote with full attestation details Description: Retrieves a single claimId within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: getQuorumVoteAttestation

Parameters:

Responses:

POST /v1/governance/quorum/votes/cast

Summary: Cast a signed quorum vote (sov-signed-artifact-v1) Description: Casts a cast within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: castSignedQuorumVote Request body:

Content type: application/json

Responses:

POST /v1/governance/quorum/votes/verify

Summary: Verify quorum vote signing artifact Description: Validates and verifies verify within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: verifyQuorumVoteSigning Request body:

Content type: application/json

Responses:

POST /v1/governance/quorum/votes/{claimId}/upgrade-signing

Summary: Upgrade legacy quorum vote with Ed25519 signing Description: Processes upgrade signing within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: upgradeQuorumVoteSigning

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/governance/quorum/{subjectScopeId}/signing-session/mint

Summary: Mint T3-quorum scoped signing session Description: Mints a mint within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: mintQuorumSigningSession

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/governance/quorum/{subjectScopeId}/votes/sign-dev

Summary: Dev helper: sign a new quorum vote cast Description: Signs sign dev within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: signDevQuorumVoteCast

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/governance/entity-blueprints

Summary: List entity blueprints with optional entity_type filter Description: Retrieves a paginated list of entity blueprints within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: listEntityBlueprints

Parameters:

Responses:

POST /v1/governance/entity-blueprints

Summary: Register a new entity blueprint (idempotent) Description: Registers a new entity blueprints within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: registerEntityBlueprint Request body:

Content type: application/json

Responses:

GET /v1/governance/entity-blueprints/types

Summary: List available entity types and default blueprints Description: Retrieves a paginated list of types within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: listEntityBlueprintTypes Responses:

GET /v1/governance/entity-blueprints/{blueprintId}

Summary: Get a single entity blueprint by ID Description: Retrieves a single blueprintId within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: getEntityBlueprint

Parameters:

Responses:

GET /v1/governance/entity-blueprints/{blueprintId}/provisions

Summary: List provisions by blueprint Description: Retrieves a paginated list of provisions within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: listEntityBlueprintProvisions

Parameters:

Responses:

POST /v1/governance/entity-blueprints/provision

Summary: Provision a single entity from a blueprint Description: Provisions a new provision within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: provisionSingleEntity Request body:

Content type: application/json

Responses:

POST /v1/governance/entity-blueprints/provision/batch

Summary: Provision multiple entities from blueprints (batch, max 25) Description: Provisions a new batch within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: provisionEntityBatch Request body:

Content type: application/json

Responses:

GET /v1/governance/entity-blueprints/entity/{entityId}

Summary: Get entity with lifecycle FSM state Description: Retrieves a single entityId within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: getEntityWithLifecycle

Parameters:

Responses:

POST /v1/governance/registration/attest

Summary: Issue government NGO registration attestation (W4-2) Description: Processes attest within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: issueRegistrationAttestation Request body:

Content type: application/json

Responses:

POST /v1/governance/broadcast/quarterly

Summary: Run quarterly broadcast query job (W4-3) Description: Processes quarterly within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: runQuarterlyBroadcast Request body:

Content type: application/json

Responses:

POST /v1/governance/ke/occupancy/check

Summary: Kenya occupancy built-vs-approved gate (W4-4) Description: Checks check within the policy evaluation, attestation, broadcast, audit, and compliance domain

Tags: governance Operation ID: checkOccupancyGate Request body:

Content type: application/json

Responses:

POST /v1/guard/evaluate

Summary: Pre-Verification Guard evaluate (W5-2) Description: Evaluates evaluate within the pre-verification guard and forensic scoring domain

Tags: guard Operation ID: evaluatePreVerificationGuard

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/vapps/feed-heartbeat

Summary: Report input feed health for virtual app (W4-5) Description: Processes feed heartbeat within the virtual app feed health and degraded status detection domain

Tags: vapp Operation ID: vappFeedHeartbeat Request body:

Content type: application/json

Responses:

GET /v1/vapps/{virtualAppId}/health

Summary: Evaluate vapp feed dependencies Description: Retrieves a single health within the virtual app feed health and degraded status detection domain

Tags: vapp Operation ID: getVappHealth

Parameters:

Responses:

POST /v1/templates/validate

Summary: Validate STP package offline or via BFF Description: Validates a Sovereign Template Package (STP) against the schema, checks module dependencies, verifies CNS catalog references, and runs the STP linter. Returns per-module pass/fail with issues. Use before applyTemplate to catch configuration errors. Supports offline mode for CI pipelines.

Tags: templates Operation ID: validateTemplate Responses:

POST /v1/templates/apply

Summary: Apply STP package to org/vapp Description: Applies an STP package: provisions org, registers manifests, seeds datasets, and configures feeds. Dry-run mode available (dry_run: true). Validates cell tier policy before applying. Returns per-phase results. Idempotent — re-apply with same package skips unchanged modules.

Tags: templates Operation ID: applyTemplate Responses:

POST /v1/commerce/subscriptions

Summary: Create a commercial subscription for a manifest Description: Creates a commercial subscription linking a manifest to a billing model. Validates billing model exists and manifest is registered. Returns subscription_id and billing status. G1-G4 commerce guards enforced. Idempotent per manifest context.

Tags: commerce Operation ID: createCommercialSubscription Responses:

GET /v1/commerce/subscriptions/sync-status

Summary: Dual/triple-write sync status (s35 + control plane + commercial_subscription) Description: Processes sync status within the commercial subscriptions, products, financial gate, and billing domain

Tags: commerce Operation ID: commerceSyncStatus Responses:

GET /v1/commerce/status

Summary: Commerce stack operator status (guards, sync, deprecations) Description: Processes status within the commercial subscriptions, products, financial gate, and billing domain

Tags: commerce Operation ID: commerceStackStatus Responses:

POST /v1/subscriptions/authorize

Summary: Authorize NATS subscription with claims + billing check (GAP-C02) Description: Authorizes authorize within the commercial subscriptions, products, financial gate, and billing domain

Tags: commerce Operation ID: authorizeSubscription Responses:

GET /v1/platform/production-readiness

Summary: Production readiness assessment Description: Comprehensive check of all production subsystems: Stripe, NATS, ZKP verifier, pre-verification guard, commerce guards, federation, placement config, UIC crypto, scoped signing. Returns per-subsystem status, warnings, and a top-level production_ready boolean. Use this to verify the platform is ready for live traffic.

Tags: platform Operation ID: productionReadiness Responses:

POST /v1/orders

Summary: Create BCO order process Description: Creates a new orders within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order Operation ID: createOrder Request body:

Content type: application/json

Responses:

GET /v1/orders/{processId}

Summary: Get order process claim Description: Retrieves a single processId within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order Operation ID: getOrderProcess

Parameters:

Responses:

POST /v1/orders/{processId}/evaluate

Summary: TGC rank candidates (dispatches order.candidates.score egress) Description: Evaluates evaluate within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order Operation ID: evaluateOrder

Parameters:

Responses:

POST /v1/orders/{processId}/award

Summary: Award offer to process (dispatches order.award.commit egress) Description: Processes award within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order Operation ID: awardOrder

Parameters:

Responses:

POST /v1/orders/{processId}/orchestrate

Summary: Spawn billing/comms branches (dispatches order.orchestrate.enter egress) Description: Processes orchestrate within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order Operation ID: orchestrateOrder

Parameters:

Responses:

POST /v1/orders/{processId}/communications/materialized

Summary: s37-lite bridge materialized message into order comm thread Description: Bridges materialized within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order Operation ID: bridgeMaterializedMessage

Parameters:

Responses:

POST /v1/orders/{processId}/communications/bridge

Summary: Bridge message into order comm thread (signing-guarded) Description: Bridges bridge within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order, signing Operation ID: bridgeOrderCommunication

Parameters:

Responses:

GET /v1/orders/communications/{commClaimId}/messages

Summary: List communication_claim messages Description: Retrieves a single messages within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order, signing Operation ID: getCommMessages

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/messages

Summary: Append signed message to comm thread Description: Processes messages within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order, signing Operation ID: appendCommMessage

Parameters:

Responses:

GET /v1/orders/communications/{commClaimId}/export

Summary: Export Profile A transcript bundle (or JWS/COSE views) Description: Exports export within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order, signing Operation ID: exportCommTranscript

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/finalize

Summary: Finalize high-stakes comm transcript (dual co-sign + PoCE GPR) Description: Processes finalize within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order, signing, governance Operation ID: finalizeCommTranscript

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/finalize/sign-dev

Summary: Dev-only: sign sov-transcript-finalize-v1 cosignature Description: Signs sign dev within the BCO order process graph: create, evaluate, award, orchestrate domain

Tags: order, signing Operation ID: signDevCommTranscriptFinalize

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/signing-session/mint

Summary: Mint T3 context signing session Description: Mints a mint within the signing domain

Tags: signing Operation ID: mintCommSigningSession

Parameters:

Responses:

POST /v1/orders/communications/verify-bundle

Summary: Verify Profile A transcript bundle Description: Validates and verifies verify bundle within the signing domain

Tags: signing Operation ID: verifyCommTranscriptBundle

Parameters:

Responses:

POST /v1/identity/signing-session/revoke

Summary: Revoke an in-memory scoped signing session Description: Processes revoke within the signing domain

Tags: signing Operation ID: revokeSigningSession Responses:

POST /v1/identity/signing-session/mint

Summary: Mint T2 daily signing session Description: Mints a mint within the signing domain

Tags: signing Operation ID: mintDailySigningSession Responses:

POST /v1/identity/signing-session/verify

Summary: Verify signed artifact Description: Validates and verifies verify within the signing domain

Tags: signing Operation ID: verifySigningArtifact Responses:

POST /v1/orders/communications/{commClaimId}/external/signing-session/mint

Summary: Mint T3-external session for Profile C detached sign Description: Mints a mint within the signing domain

Tags: signing Operation ID: mintExternalSigningSession

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/external/sign-dev

Summary: Dev-only: sign Profile C external sidecar Description: Signs sign dev within the signing domain

Tags: signing Operation ID: signDevExternalSidecar

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/external/verify

Summary: Verify Profile C external sidecar against payload Description: Validates and verifies verify within the signing domain

Tags: signing Operation ID: verifyExternalSidecar

Parameters:

Responses:

POST /v1/orders/communications/{commClaimId}/external/record

Summary: Verify + file external sidecar to vault (idempotent) Description: Records record within the signing domain

Tags: signing Operation ID: recordExternalSidecar

Parameters:

Responses:

POST /v1/governance/external/verify-detached

Summary: Verify detached Profile C sidecar (comm id in artifact) Description: Validates and verifies verify detached within the signing domain

Tags: signing, governance Operation ID: verifyDetachedExternalSidecar Responses:

POST /v1/tgc/evaluate

Summary: Evaluate TGC criteria against candidate Description: Processes evaluate within the Truth Graph Criteria matching and candidate ranking domain

Tags: tgc Operation ID: tgcEvaluate Responses:

GET /v1/standing-orders

Summary: List active standing orders Description: Retrieves a paginated list of standing orders within the standing-order domain

Tags: standing-order Operation ID: listStandingOrders Responses:

POST /v1/standing-orders

Summary: Register standing order Description: Registers a new standing orders within the standing-order domain

Tags: standing-order Operation ID: registerStandingOrder Responses:

POST /v1/standing-orders/inventory-tick

Summary: Push inventory update (primary standing-order trigger) Description: Processes inventory tick within the standing-order domain

Tags: standing-order Operation ID: standingOrderInventoryTick Responses:

GET /v1/crm/pipeline/stages

Summary: List pipeline stages by kind Description: Retrieves a paginated list of stages within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listPipelineStages

Parameters:

Responses:

GET /v1/crm/pipeline/stages/{stageId}

Summary: Get pipeline stage by ID Description: Retrieves a single stageId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getPipelineStage

Parameters:

Responses:

POST /v1/crm/pipeline/stages/init

Summary: Initialize default pipeline stages Description: Processes init within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: initPipelineStages Request body:

Content type: application/json

Responses:

GET /v1/crm/pipeline/{pipelineKind}

Summary: List pipeline with opportunities by kind Description: Retrieves a paginated list of pipelineKind within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listPipeline

Parameters:

Responses:

GET /v1/pipeline/hooks

Summary: List registered pipeline hook handlers Description: Retrieves a paginated list of hooks within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: listPipelineHooks Responses:

GET /v1/pipeline/docs

Summary: Pipeline system documentation Description: Retrieves a single docs within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: getPipelineDocs Responses:

POST /v1/pipeline/definitions

Summary: Register a pipeline FSM definition Description: Registers a new definitions within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: registerPipelineDefinition Request body:

Content type: application/json

Responses:

GET /v1/pipeline/definitions

Summary: List all pipeline definitions Description: Retrieves a paginated list of definitions within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: listPipelineDefinitions Responses:

GET /v1/pipeline/definitions/{defId}

Summary: Get a pipeline definition by ID Description: Retrieves a single defId within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: getPipelineDefinition

Parameters:

Responses:

POST /v1/pipeline/definitions/{defId}/load

Summary: Load (activate) a pipeline definition Description: Loads load within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: loadPipelineDefinition

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/pipeline/instances

Summary: Start a pipeline instance from a loaded definition Description: Creates and starts a new pipeline instance from a registered definition. Validates the definition exists and is loaded. Binds the FSM to a resource if resource_id provided. Returns the new instance_id and initial state. The instance can then be advanced via executePipelineTransition.

Tags: pipeline Operation ID: startPipelineInstance Request body:

Content type: application/json

Responses:

GET /v1/pipeline/instances

Summary: List pipeline instances Description: Retrieves a paginated list of instances within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: listPipelineInstances

Parameters:

Responses:

GET /v1/pipeline/instances/{bindingId}

Summary: Get pipeline instance status Description: Retrieves a single bindingId within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: getPipelineInstance

Parameters:

Responses:

POST /v1/pipeline/instances/{bindingId}/transition

Summary: Execute a pipeline stage transition Description: Executes transition within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: executePipelineTransition

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/pipeline/instances/{bindingId}/checkpoint

Summary: Get current checkpoint for a pipeline instance Description: Retrieves a single checkpoint within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: getPipelineCheckpoint

Parameters:

Responses:

POST /v1/pipeline/instances/{bindingId}/checkpoint

Summary: Manually save a pipeline checkpoint Description: Saves checkpoint within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: savePipelineCheckpoint

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/pipeline/instances/{bindingId}/resume

Summary: Resume a pipeline from its last checkpoint Description: Resumes resume within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: resumePipeline

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/pipeline/instances/{bindingId}/ingress

Summary: Webhook ingress for pipeline instances Description: Processes ingress within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: pipelineIngress

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/pipeline/bundle

Summary: Register + load + start a pipeline in one call Description: Activates bundle within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain

Tags: pipeline Operation ID: activatePipeline Request body:

Content type: application/json

Responses:

POST /v1/chat/webhook/{platform}/{bindingId}

Summary: Receive platform webhook message (WhatsApp, Telegram, Slack, Discord, SMS) Description: Production webhook endpoint for receiving inbound messages from any supported platform. Verifies the binding, normalizes the message via chat:inbox_ingest hook, routes through pipeline FSM, and dispatches to registered bot agents (Dify, LLM, human handoff). Supports Twilio SMS, WhatsApp Business, Telegram, Slack, and Discord formats. Returns 202 accepted.

Tags: chat Operation ID: chatWebhookIngest

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/chat/health

Summary: Chat subsystem health check Description: Processes health within the omnichannel chat: webhook ingestion, platform adapters, bot agents, handoff domain

Tags: chat Operation ID: chatHealth Responses:

POST /v1/crm/contacts

Summary: Create or update a CRM contact Description: Creates or updates contacts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: upsertContact Request body:

Content type: application/json

Responses:

GET /v1/crm/contacts

Summary: List contacts Description: Retrieves a paginated list of contacts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listContacts

Parameters:

Responses:

GET /v1/crm/contacts/{contactId}

Summary: Get contact by ID Description: Retrieves a single contactId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getContact

Parameters:

Responses:

POST /v1/crm/leads

Summary: Create a CRM lead Description: Creates a new leads within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: createLead Request body:

Content type: application/json

Responses:

GET /v1/crm/leads

Summary: List leads with optional filters Description: Retrieves a paginated list of leads within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listLeads

Parameters:

Responses:

GET /v1/crm/leads/{leadId}

Summary: Get lead by ID Description: Retrieves a single leadId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getLead

Parameters:

Responses:

POST /v1/crm/leads/{leadId}/score

Summary: Score a lead Description: Scores score within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: scoreLead

Parameters:

Responses:

POST /v1/crm/opportunities

Summary: Create a CRM opportunity Description: Creates a new opportunities within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: createOpportunity Request body:

Content type: application/json

Responses:

GET /v1/crm/opportunities

Summary: List opportunities with optional filters Description: Retrieves a paginated list of opportunities within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listOpportunities

Parameters:

Responses:

GET /v1/crm/opportunities/{opportunityId}

Summary: Get opportunity by ID Description: Retrieves a single opportunityId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getOpportunity

Parameters:

Responses:

POST /v1/crm/opportunities/{opportunityId}/transition

Summary: Transition opportunity to a new pipeline stage Description: Processes transition within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: transitionOpportunityStage

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/crm/interactions

Summary: Create a CRM interaction record Description: Creates a new interactions within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: createInteraction Request body:

Content type: application/json

Responses:

GET /v1/crm/interactions

Summary: List interactions by subject Description: Retrieves a paginated list of interactions within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listInteractions

Parameters:

Responses:

GET /v1/crm/interactions/{interactionId}

Summary: Get interaction by ID Description: Retrieves a single interactionId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getInteraction

Parameters:

Responses:

GET /v1/crm/customer-360/{entityId}

Summary: Get customer 360 view by entity ID Description: Retrieves a single entityId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getCustomer360

Parameters:

Responses:

POST /v1/crm/cohorts

Summary: Create a CRM cohort Description: Creates a new cohorts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: createCohort Request body:

Content type: application/json

Responses:

GET /v1/crm/cohorts

Summary: List cohorts Description: Retrieves a paginated list of cohorts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listCohorts

Parameters:

Responses:

GET /v1/crm/cohorts/{cohortId}

Summary: Get cohort by ID Description: Retrieves a single cohortId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getCohort

Parameters:

Responses:

GET /v1/crm/cohorts/{cohortId}/members

Summary: List cohort members Description: Retrieves a paginated list of members within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listCohortMembers

Parameters:

Responses:

POST /v1/crm/cohorts/{cohortId}/members

Summary: Add entity to cohort Description: Processes members within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: addToCohort

Parameters:

Request body:

Content type: application/json

Responses:

DELETE /v1/crm/cohorts/{cohortId}/members/{entityId}

Summary: Remove entity from cohort Description: Processes entityId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: removeFromCohort

Parameters:

Responses:

POST /v1/crm/campaigns

Summary: Create a CRM campaign Description: Creates a new campaigns within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: createCampaign Request body:

Content type: application/json

Responses:

GET /v1/crm/campaigns

Summary: List campaigns Description: Retrieves a paginated list of campaigns within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: listCampaigns

Parameters:

Responses:

GET /v1/crm/campaigns/{campaignId}

Summary: Get campaign by ID Description: Retrieves a single campaignId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: getCampaign

Parameters:

Responses:

POST /v1/crm/campaigns/{campaignId}/status

Summary: Update campaign status Description: Updates an existing status within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: updateCampaignStatus

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/crm/truth-graph/sync

Summary: Sync a CRM entity to the truth graph Description: Synchronizes sync within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain

Tags: crm Operation ID: syncCrmToTruthGraph Request body:

Content type: application/json

Responses:

GET /v1/openapi.json

Summary: This OpenAPI fragment (JSON) Description: Retrieves a single openapi.json within the meta domain

Tags: meta Operation ID: getOpenApiJson Responses:

PUT /v1/enterprise/idp/{providerId}/saml

Summary: Update SAML configuration for an IdP Description: Updates an existing saml within the enterprise-identity domain

Tags: enterprise-identity Operation ID: updateIdpSamlConfig

Parameters:

Request body:

Content type: application/json

Responses:

PUT /v1/enterprise/idp/{providerId}/ldap

Summary: Update LDAP configuration for an IdP Description: Updates an existing ldap within the enterprise-identity domain

Tags: enterprise-identity Operation ID: updateIdpLdapConfig

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/enterprise/idp/{providerId}/resolve-saml

Summary: Resolve SAML assertion attributes Description: Processes resolve saml within the enterprise-identity domain

Tags: enterprise-identity Operation ID: resolveSamlAttributes

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/enterprise/idp/{providerId}/group-mappings

Summary: List active group→role mappings Description: Retrieves a single group mappings within the enterprise-identity domain

Tags: enterprise-identity Operation ID: getIdpGroupMappings

Parameters:

Responses:

POST /v1/enterprise/idp/{providerId}/group-mappings

Summary: Create/update group→role mapping Description: Processes group mappings within the enterprise-identity domain

Tags: enterprise-identity Operation ID: mapIdpGroupToRole

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/enterprise/idp/{providerId}/resolve-roles

Summary: Resolve enterprise roles from IdP group memberships Description: Processes resolve roles within the enterprise-identity domain

Tags: enterprise-identity Operation ID: resolveEnterpriseRoles

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/enterprise/idp/{providerId}/health

Summary: Record IdP health check result Description: Checks health within the enterprise-identity domain

Tags: enterprise-identity Operation ID: checkIdpHealth

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/enterprise/idp/{providerId}/sync

Summary: Record a group sync run Description: Records sync within the enterprise-identity domain

Tags: enterprise-identity Operation ID: recordIdpSync

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/enterprise/idp/needing-sync

Summary: Find IdPs due for group sync Description: Retrieves a paginated list of needing sync within the enterprise-identity domain

Tags: enterprise-identity Operation ID: listProvidersNeedingSync Responses:

GET /v1/enterprise/idp/unhealthy

Summary: Find IdPs needing health attention Description: Retrieves a paginated list of unhealthy within the enterprise-identity domain

Tags: enterprise-identity Operation ID: listUnhealthyProviders Responses:

GET /v1/enterprise/idp/stats

Summary: Aggregated IdP statistics Description: Retrieves a single stats within the enterprise-identity domain

Tags: enterprise-identity Operation ID: getIdpStats Responses:

DELETE /v1/enterprise/idp/group-mappings/{mappingId}

Summary: Deactivate a group mapping Description: Processes mappingId within the enterprise-identity domain

Tags: enterprise-identity Operation ID: removeIdpGroupMapping

Parameters:

Responses:

POST /v1/enterprise/brokers

Summary: Register a new broker configuration Description: Registers a new brokers within the identity-broker domain

Tags: identity-broker Operation ID: registerBroker Request body:

Content type: application/json

Responses:

POST /v1/enterprise/brokers/{brokerId}/resolve

Summary: Resolve external identity to universal_claim_id Description: Processes resolve within the identity-broker domain

Tags: identity-broker Operation ID: resolveIdentity

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/enterprise/brokers/{brokerId}/links

Summary: Create a manual identity broker link Description: Creates a new links within the identity-broker domain

Tags: identity-broker Operation ID: createBrokerLink

Parameters:

Request body:

Content type: application/json

Responses:

DELETE /v1/enterprise/brokers/links/{linkId}

Summary: Revoke (soft-delete) an identity broker link Description: Processes linkId within the identity-broker domain

Tags: identity-broker Operation ID: revokeBrokerLink

Parameters:

Responses:

GET /v1/enterprise/brokers/links/user/{universalClaimId}

Summary: Get active broker links for a user Description: Retrieves a single universalClaimId within the identity-broker domain

Tags: identity-broker Operation ID: getUserBrokerLinks

Parameters:

Responses:

GET /v1/enterprise/brokers/{brokerId}/tenant/{externalOrgId}

Summary: Resolve external org to sovereign tenant Description: Processes externalOrgId within the identity-broker domain

Tags: identity-broker Operation ID: resolveBrokerTenant

Parameters:

Responses:

POST /v1/enterprise/brokers/{brokerId}/org-mappings

Summary: Register org mapping for a broker Description: Registers a new org mappings within the identity-broker domain

Tags: identity-broker Operation ID: registerBrokerOrgMapping

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/enterprise/brokers/identities/{universalClaimId}

Summary: List external identities mapped to a universal_claim_id Description: Retrieves a single universalClaimId within the identity-broker domain

Tags: identity-broker Operation ID: getExternalIdentities

Parameters:

Responses:

POST /v1/enterprise/brokers/sweep

Summary: Sweep and deactivate expired broker links Description: Processes sweep within the identity-broker domain

Tags: identity-broker Operation ID: sweepExpiredBrokerLinks

Parameters:

Responses:

GET /v1/enterprise/brokers/stats

Summary: Aggregated broker statistics Description: Retrieves a single stats within the identity-broker domain

Tags: identity-broker Operation ID: getBrokerStats Responses:

POST /v1/enterprise/idp/sweep-sync

Summary: Manual sweep of providers needing sync Description: Processes sweep sync within the identity-sync domain

Tags: identity-sync Operation ID: sweepIdpSync

Parameters:

Responses:

GET /v1/enterprise/idp/sync/status

Summary: Identity sync engine status and stats Description: Retrieves a single status within the identity-sync domain

Tags: identity-sync Operation ID: getIdpSyncStatus Responses:

POST /v1/enterprise/idp/sweep-events

Summary: Manual event consumer sweep Description: Processes sweep events within the identity-sync domain

Tags: identity-sync Operation ID: sweepIdpSyncEvents

Parameters:

Responses:

POST /v1/enterprise/idp/enqueue-sync/{providerId}

Summary: Enqueue sync event for a specific provider Description: Processes providerId within the identity-sync domain

Tags: identity-sync Operation ID: enqueueProviderSync

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/enterprise/idp/enqueue-sync-all

Summary: Enqueue sync events for all active providers Description: Processes enqueue sync all within the identity-sync domain

Tags: identity-sync Operation ID: enqueueAllProviderSyncs Responses:

POST /v1/enterprise/idp/sync/start

Summary: Start the periodic sync consumer Description: Starts a new start within the identity-sync domain

Tags: identity-sync Operation ID: startIdpSyncConsumer Request body:

Content type: application/json

Responses:

POST /v1/enterprise/idp/sync/stop

Summary: Stop the periodic sync consumer Description: Stops stop within the identity-sync domain

Tags: identity-sync Operation ID: stopIdpSyncConsumer Responses:

POST /v1/sso/sessions

Summary: Create a new SSO session from a Keycloak link Description: Creates a new sessions within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: createSsoSession Request body:

Content type: application/json

Responses:

GET /v1/sso/sessions/{sessionId}

Summary: Validate and retrieve SSO session status Description: Processes sessionId within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: validateSsoSession

Parameters:

Responses:

POST /v1/sso/sessions/{sessionId}/refresh

Summary: Extend an SSO session's expiration Description: Processes refresh within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: refreshSsoSession

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/sso/sessions/{sessionId}/revoke

Summary: Revoke an SSO session (with optional KC cascade) Description: Processes revoke within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: revokeSsoSession

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/sso/sessions/user/{subjectId}

Summary: List active SSO sessions for a user Description: Retrieves a single subjectId within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: getUserSsoSessions

Parameters:

Responses:

POST /v1/sso/sweep

Summary: Sweep and cleanup expired SSO sessions Description: Processes sweep within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: sweepExpiredSsoSessions

Parameters:

Responses:

GET /v1/sso/stats

Summary: SSO session statistics Description: Retrieves a single stats within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain

Tags: sso Operation ID: getSsoStats Responses:

Full specification — verbatim source of truth

{
  "openapi": "3.1.0",
  "info": {
    "title": "Sovereign Agent BFF — manifest & workspace fragment",
    "version": "1.0.0",
    "description": "OpenAPI 3.1 fragment (W5-5) for semantic manifest, workspace, governance, guard, and vapp health routes on sovereign-bff :3030."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3030",
      "description": "Local dev (DEV_SKIP_AUTH=1)"
    }
  ],
  "tags": [
    {
      "name": "manifest",
      "description": "Semantic manifest register and resolve (s97)"
    },
    {
      "name": "workspace",
      "description": "Org membership and virtual apps (s100)"
    },
    {
      "name": "governance",
      "description": "Policy evaluation, attestation, broadcast, KE audit"
    },
    {
      "name": "guard",
      "description": "Pre-Verification Guard (W5-2)"
    },
    {
      "name": "vapp",
      "description": "Virtual app feed health / degraded status (W4-5)"
    },
    {
      "name": "templates",
      "description": "Sovereign Template Package validate/plan/apply"
    },
    {
      "name": "commerce",
      "description": "Commercial subscriptions, products, financial gate (s101)"
    },
    {
      "name": "platform",
      "description": "Production readiness and operator status"
    },
    {
      "name": "order",
      "description": "BCO order process graph (s114–s118)"
    },
    {
      "name": "tgc",
      "description": "Truth Graph Criteria matching (s113)"
    },
    {
      "name": "standing-order",
      "description": "TGC standing orders + inventory tick (s117)"
    },
    {
      "name": "crm",
      "description": "CRM coordination — pipeline, contacts, leads, opportunities, cohorts, campaigns (s145)"
    },
    {
      "name": "pipeline",
      "description": "Declarative FSM pipeline engine — definitions, instances, transitions, checkpoints, hooks (pipeline-engine)"
    },
    {
      "name": "chat",
      "description": "Omnichannel chat — webhook endpoints, platform adapters, AI bot agents, human handoff (s7)"
    },
    {
      "name": "enterprise-identity",
      "description": "Enterprise IdP management — SAML, LDAP, group mappings, health checks, sync (s177)"
    },
    {
      "name": "identity-broker",
      "description": "Cross-org identity resolution, tenant routing, federated linking (s178)"
    },
    {
      "name": "identity-sync",
      "description": "Identity sync engine — periodic sweep, event-driven consumers, enqueue (s180)"
    },
    {
      "name": "sso",
      "description": "SSO session management — create, validate, refresh, revoke Keycloak sessions (s181)"
    }
  ],
  "paths": {
    "/v1/manifests": {
      "get": {
        "tags": [
          "manifest"
        ],
        "summary": "List registered manifests",
        "description": "Returns all registered manifests filtered by optional query params. Each manifest contains provider_id, organization_id, virtual_app_id, and contract_implementations. Use this to discover available services before calling resolveManifestCommunication.",
        "operationId": "listManifests",
        "responses": {
          "200": {
            "description": "Manifest summaries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "manifest"
        ],
        "summary": "Register manifest (v2 implementation_context)",
        "description": "Register or update a manifest with v2 implementation context. Creates organization, virtual app, and contract bindings. Requires governance policy compliance. Idempotent — re-registering an existing provider_id updates the manifest. Side effects: federation sync, scope advertisement, pre-verification guard check.",
        "operationId": "registerManifest",
        "parameters": [
          {
            "name": "X-Forensic-Score",
            "in": "header",
            "schema": {
              "type": "number"
            },
            "description": "Optional Pre-Verification Guard score override"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManifestRegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestRegisterResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationProblem"
          },
          "403": {
            "$ref": "#/components/responses/GuardProblem"
          }
        }
      }
    },
    "/v1/manifests/{providerId}": {
      "get": {
        "tags": [
          "manifest"
        ],
        "summary": "Get manifest by provider_id",
        "operationId": "getManifest",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderId"
          }
        ],
        "responses": {
          "200": {
            "description": "Manifest document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestRegisterResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "description": "Retrieves a single providerId within the semantic manifest register, resolve, and federation domain"
      }
    },
    "/v1/manifests/{providerId}/resolved": {
      "get": {
        "tags": [
          "manifest"
        ],
        "summary": "Resolve communication binding + CNS interface",
        "operationId": "resolveManifestCommunication",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderId"
          },
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "cns://gov/tz/compliance/employee_roster@v1.0.0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved communication"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "description": "Processes resolved within the semantic manifest register, resolve, and federation domain"
      }
    },
    "/v1/manifests/{providerId}/input-feeds": {
      "get": {
        "tags": [
          "manifest"
        ],
        "summary": "List manifest input feed declarations (streams.input)",
        "operationId": "listManifestInputFeeds",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProviderId"
          }
        ],
        "responses": {
          "200": {
            "description": "Input feed bindings"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "description": "Retrieves a paginated list of input feeds within the semantic manifest register, resolve, and federation domain"
      }
    },
    "/v1/workspace/memberships": {
      "get": {
        "tags": [
          "workspace"
        ],
        "summary": "List org memberships for user",
        "operationId": "listMemberships",
        "parameters": [
          {
            "name": "user_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Membership rows"
          }
        },
        "description": "Retrieves a paginated list of memberships within the organization membership, virtual apps, and sovereign accounts domain"
      },
      "post": {
        "tags": [
          "workspace"
        ],
        "summary": "Create or update org membership",
        "operationId": "createMembership",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MembershipCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Membership created"
          }
        },
        "description": "Creates a new memberships within the organization membership, virtual apps, and sovereign accounts domain"
      }
    },
    "/v1/workspace/virtual-apps": {
      "get": {
        "tags": [
          "workspace"
        ],
        "summary": "List virtual apps for organization",
        "operationId": "listVirtualApps",
        "parameters": [
          {
            "name": "org_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "org:ngo:kilimanjaro_aid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Virtual app rows"
          }
        },
        "description": "Retrieves a paginated list of virtual apps within the organization membership, virtual apps, and sovereign accounts domain"
      },
      "post": {
        "tags": [
          "workspace"
        ],
        "summary": "Create or update organization virtual app",
        "operationId": "createVirtualApp",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VirtualAppCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Virtual app row"
          }
        },
        "description": "Creates a new virtual apps within the organization membership, virtual apps, and sovereign accounts domain"
      }
    },
    "/v1/workspaces/org-applications": {
      "post": {
        "tags": [
          "workspace"
        ],
        "summary": "Provision organization + virtual app + manifest",
        "description": "One-call provisioning: creates org membership, sovereign account, virtual app, and registers manifest in a single transaction. Optionally creates commercial subscription and portfolio. Returns org_id, vapp_id, manifest_id. Idempotent — safe to re-call with same parameters.",
        "operationId": "provisionOrgApplication",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgApplicationProvisionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Provisioned org application"
          }
        }
      }
    },
    "/v1/governance/verify-interfaces": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Verify manifest interfaces against governance policies",
        "description": "Validates all registered manifests for an organization against governance policies, CNS catalog, and contract compliance. Returns per-binding pass/fail with detailed issues. Use after registerManifest to confirm compliance. Also runs built-vs-approved hash gate check.",
        "operationId": "verifyInterfaces",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyInterfacesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result"
          }
        }
      }
    },
    "/v1/governance/verify-organization-interfaces": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Verify all virtual apps for an organization implement required contracts",
        "operationId": "verifyOrganizationInterfaces",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "organization_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Org-wide verification result"
          }
        },
        "description": "Validates and verifies verify organization interfaces within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/fusion/traffic/enrich": {
      "post": {
        "tags": [
          "fusion"
        ],
        "summary": "Apply Google Traffic enrichment (derived output only)",
        "operationId": "enrichTrafficFusion",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider_id": {
                    "type": "string"
                  },
                  "sensor_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "regions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Derived enrichment corridors"
          }
        },
        "description": "Processes enrich within the fusion domain"
      }
    },
    "/v1/fusion/traffic/sensors/ingest": {
      "post": {
        "tags": [
          "fusion"
        ],
        "summary": "Ingest mock traffic sensor readings to ingest.gov.tz.traffic.sensors.*",
        "operationId": "ingestTrafficSensors",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "batch": {
                    "type": "boolean"
                  },
                  "corridors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "reading": {
                    "type": "object"
                  },
                  "corridor_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sensor ingest + feed/NATS publish result"
          }
        },
        "description": "Ingests ingest within the fusion domain"
      }
    },
    "/v1/fusion/import/plans/normalize": {
      "post": {
        "tags": [
          "fusion"
        ],
        "summary": "Normalize importer dialog payload to gov import plans feed",
        "operationId": "normalizeImportPlans",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payload": {
                    "type": "object"
                  },
                  "submitted_by": {
                    "type": "string"
                  },
                  "submission_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized plan + feed/NATS publish result"
          }
        },
        "description": "Processes normalize within the fusion domain"
      }
    },
    "/v1/governance/policies": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "List active governance policies",
        "operationId": "listGovernancePolicies",
        "responses": {
          "200": {
            "description": "Policy list"
          }
        },
        "description": "Retrieves a paginated list of policies within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/policies/evaluate": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Evaluate applicable policies for org/vapp context",
        "operationId": "evaluateGovernancePolicies",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyEvaluateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matched policies and required contracts"
          }
        },
        "description": "Evaluates evaluate within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/votes": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "List quorum votes with attestation status for a scope",
        "operationId": "listQuorumVotes",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Scope ID (e.g. subscope:dev:tz_compliance)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Votes with linked claims, attestations, and index status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "votes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "claims": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "attestations": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "indexed": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Retrieves a paginated list of votes within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      },
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Query quorum votes with flexible filters",
        "operationId": "queryQuorumVotes",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "scope"
                ],
                "properties": {
                  "scope": {
                    "type": "string"
                  },
                  "quorum_member": {
                    "type": "string",
                    "description": "Filter by quorum member DID"
                  },
                  "limit": {
                    "type": "integer",
                    "default": 50
                  },
                  "offset": {
                    "type": "integer",
                    "default": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Filtered votes with linked attestations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "votes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "claims": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "attestations": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "indexed": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Processes votes within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/votes/{claimId}": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "Get single quorum vote with full attestation details",
        "operationId": "getQuorumVoteAttestation",
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Claim ID linked to the quorum vote"
          }
        ],
        "responses": {
          "200": {
            "description": "Claim, vote, attestation, and index status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "claim": {
                      "type": "object"
                    },
                    "vote": {
                      "type": "object"
                    },
                    "attestation": {
                      "type": "object"
                    },
                    "indexed": {
                      "type": "object"
                    },
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing claimId parameter"
          },
          "404": {
            "description": "Claim not found"
          }
        },
        "description": "Retrieves a single claimId within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/votes/cast": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Cast a signed quorum vote (sov-signed-artifact-v1)",
        "operationId": "castSignedQuorumVote",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "scope",
                  "quorum_member"
                ],
                "properties": {
                  "scope": {
                    "type": "string"
                  },
                  "parent_scope": {
                    "type": "string"
                  },
                  "quorum_member": {
                    "type": "string"
                  },
                  "ballot": {
                    "type": "string",
                    "default": "approve"
                  },
                  "signing": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vote recorded"
          },
          "403": {
            "description": "Invalid signature"
          }
        },
        "description": "Casts a cast within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/votes/verify": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Verify quorum vote signing artifact",
        "operationId": "verifyQuorumVoteSigning",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result"
          }
        },
        "description": "Validates and verifies verify within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/votes/{claimId}/upgrade-signing": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Upgrade legacy quorum vote with Ed25519 signing",
        "operationId": "upgradeQuorumVoteSigning",
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signing upgraded"
          }
        },
        "description": "Processes upgrade signing within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/{subjectScopeId}/signing-session/mint": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Mint T3-quorum scoped signing session",
        "operationId": "mintQuorumSigningSession",
        "parameters": [
          {
            "name": "subjectScopeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session minted"
          }
        },
        "description": "Mints a mint within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/quorum/{subjectScopeId}/votes/sign-dev": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Dev helper: sign a new quorum vote cast",
        "operationId": "signDevQuorumVoteCast",
        "parameters": [
          {
            "name": "subjectScopeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signing block for cast"
          }
        },
        "description": "Signs sign dev within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "List entity blueprints with optional entity_type filter",
        "operationId": "listEntityBlueprints",
        "parameters": [
          {
            "name": "entity_type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "organization",
                "team",
                "community"
              ]
            },
            "description": "Filter by entity kind"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Blueprints with total count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blueprints": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Retrieves a paginated list of entity blueprints within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      },
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Register a new entity blueprint (idempotent)",
        "operationId": "registerEntityBlueprint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "blueprint_id",
                  "entity_kind",
                  "display_name"
                ],
                "properties": {
                  "blueprint_id": {
                    "type": "string",
                    "description": "Unique blueprint ID"
                  },
                  "entity_kind": {
                    "type": "string",
                    "enum": [
                      "organization",
                      "team",
                      "community"
                    ]
                  },
                  "version": {
                    "type": "string",
                    "default": "1.0.0"
                  },
                  "display_name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "lifecycle_fsm_type": {
                    "type": "string"
                  },
                  "config": {
                    "type": "object"
                  },
                  "default_roles": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "claim_types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "created_by": {
                    "type": "string",
                    "default": "system:deploy"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Blueprint registered"
          }
        },
        "description": "Registers a new entity blueprints within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints/types": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "List available entity types and default blueprints",
        "operationId": "listEntityBlueprintTypes",
        "responses": {
          "200": {
            "description": "Entity types and default blueprint references",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "types": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "default_blueprints": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Retrieves a paginated list of types within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints/{blueprintId}": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "Get a single entity blueprint by ID",
        "operationId": "getEntityBlueprint",
        "parameters": [
          {
            "name": "blueprintId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Blueprint with provision count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blueprint": {
                      "type": "object"
                    },
                    "provision_count": {
                      "type": "integer"
                    },
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Blueprint not found"
          }
        },
        "description": "Retrieves a single blueprintId within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints/{blueprintId}/provisions": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "List provisions by blueprint",
        "operationId": "listEntityBlueprintProvisions",
        "parameters": [
          {
            "name": "blueprintId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "entity_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Provision rows",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provisions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Retrieves a paginated list of provisions within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints/provision": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Provision a single entity from a blueprint",
        "operationId": "provisionSingleEntity",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entity_type",
                  "blueprint_id",
                  "entity_id",
                  "slug",
                  "display_name"
                ],
                "properties": {
                  "entity_type": {
                    "type": "string",
                    "enum": [
                      "organization",
                      "team",
                      "community"
                    ]
                  },
                  "blueprint_id": {
                    "type": "string"
                  },
                  "entity_id": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "display_name": {
                    "type": "string"
                  },
                  "actor": {
                    "type": "string",
                    "default": "system:deploy"
                  },
                  "config": {
                    "type": "object"
                  },
                  "organization": {
                    "type": "string",
                    "description": "Required for team and community entities"
                  },
                  "description": {
                    "type": "string"
                  },
                  "community_id": {
                    "type": "string"
                  },
                  "parent_team_id": {
                    "type": "string"
                  },
                  "visibility": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Provision result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "entity_id": {
                      "type": "string"
                    },
                    "blueprint_id": {
                      "type": "string"
                    },
                    "already_provisioned": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Provisions a new provision within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints/provision/batch": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Provision multiple entities from blueprints (batch, max 25)",
        "operationId": "provisionEntityBatch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "requests"
                ],
                "properties": {
                  "requests": {
                    "type": "array",
                    "maxItems": 25,
                    "items": {
                      "type": "object",
                      "properties": {
                        "entity_type": {
                          "type": "string",
                          "enum": [
                            "organization",
                            "team",
                            "community"
                          ]
                        },
                        "blueprint_id": {
                          "type": "string"
                        },
                        "entity_id": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "display_name": {
                          "type": "string"
                        },
                        "actor": {
                          "type": "string"
                        },
                        "config": {
                          "type": "object"
                        },
                        "organization": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "default_actor": {
                    "type": "string",
                    "default": "system:deploy"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch result with summary counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "succeeded": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid batch request (empty or exceeds 25)"
          }
        },
        "description": "Provisions a new batch within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/entity-blueprints/entity/{entityId}": {
      "get": {
        "tags": [
          "governance"
        ],
        "summary": "Get entity with lifecycle FSM state",
        "operationId": "getEntityWithLifecycle",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "table",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Override: organization, team, or community"
            }
          },
          {
            "name": "id_field",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Override: org_id, team_id, or community_id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity with lifecycle FSM state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entity": {
                      "type": "object"
                    },
                    "lifecycle_fsm": {
                      "type": "object"
                    },
                    "provision": {
                      "type": "object"
                    },
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Entity not found"
          }
        },
        "description": "Retrieves a single entityId within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/registration/attest": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Issue government NGO registration attestation (W4-2)",
        "operationId": "issueRegistrationAttestation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Attestation issued"
          }
        },
        "description": "Processes attest within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/broadcast/quarterly": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Run quarterly broadcast query job (W4-3)",
        "operationId": "runQuarterlyBroadcast",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Broadcast job recorded"
          }
        },
        "description": "Processes quarterly within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/governance/ke/occupancy/check": {
      "post": {
        "tags": [
          "governance"
        ],
        "summary": "Kenya occupancy built-vs-approved gate (W4-4)",
        "operationId": "checkOccupancyGate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "project_id"
                ],
                "properties": {
                  "project_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Occupancy gate result"
          }
        },
        "description": "Checks check within the policy evaluation, attestation, broadcast, audit, and compliance domain"
      }
    },
    "/v1/guard/evaluate": {
      "post": {
        "tags": [
          "guard"
        ],
        "summary": "Pre-Verification Guard evaluate (W5-2)",
        "operationId": "evaluatePreVerificationGuard",
        "parameters": [
          {
            "name": "X-Forensic-Score",
            "in": "header",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "X-Caller-Claims",
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SCAF-Hop-Count",
            "in": "header",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GuardEvaluateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Allowed (possibly redacted payload)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuardEvaluateResponse"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/GuardProblem"
          }
        },
        "description": "Evaluates evaluate within the pre-verification guard and forensic scoring domain"
      }
    },
    "/v1/vapps/feed-heartbeat": {
      "post": {
        "tags": [
          "vapp"
        ],
        "summary": "Report input feed health for virtual app (W4-5)",
        "operationId": "vappFeedHeartbeat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VappFeedHeartbeatRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Feed health row"
          }
        },
        "description": "Processes feed heartbeat within the virtual app feed health and degraded status detection domain"
      }
    },
    "/v1/vapps/{virtualAppId}/health": {
      "get": {
        "tags": [
          "vapp"
        ],
        "summary": "Evaluate vapp feed dependencies",
        "operationId": "getVappHealth",
        "parameters": [
          {
            "name": "virtualAppId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "provider_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Health evaluation"
          }
        },
        "description": "Retrieves a single health within the virtual app feed health and degraded status detection domain"
      }
    },
    "/v1/templates/validate": {
      "post": {
        "tags": [
          "templates"
        ],
        "summary": "Validate STP package offline or via BFF",
        "description": "Validates a Sovereign Template Package (STP) against the schema, checks module dependencies, verifies CNS catalog references, and runs the STP linter. Returns per-module pass/fail with issues. Use before applyTemplate to catch configuration errors. Supports offline mode for CI pipelines.",
        "operationId": "validateTemplate",
        "responses": {
          "200": {
            "description": "Validation result"
          }
        }
      }
    },
    "/v1/templates/apply": {
      "post": {
        "tags": [
          "templates"
        ],
        "summary": "Apply STP package to org/vapp",
        "description": "Applies an STP package: provisions org, registers manifests, seeds datasets, and configures feeds. Dry-run mode available (dry_run: true). Validates cell tier policy before applying. Returns per-phase results. Idempotent — re-apply with same package skips unchanged modules.",
        "operationId": "applyTemplate",
        "responses": {
          "201": {
            "description": "Apply phases"
          }
        }
      }
    },
    "/v1/commerce/subscriptions": {
      "post": {
        "tags": [
          "commerce"
        ],
        "summary": "Create a commercial subscription for a manifest",
        "description": "Creates a commercial subscription linking a manifest to a billing model. Validates billing model exists and manifest is registered. Returns subscription_id and billing status. G1-G4 commerce guards enforced. Idempotent per manifest context.",
        "operationId": "createCommercialSubscription",
        "responses": {
          "201": {
            "description": "Commercial subscription envelope"
          }
        }
      }
    },
    "/v1/commerce/subscriptions/sync-status": {
      "get": {
        "tags": [
          "commerce"
        ],
        "summary": "Dual/triple-write sync status (s35 + control plane + commercial_subscription)",
        "operationId": "commerceSyncStatus",
        "responses": {
          "200": {
            "description": "Sync status"
          }
        },
        "description": "Processes sync status within the commercial subscriptions, products, financial gate, and billing domain"
      }
    },
    "/v1/commerce/status": {
      "get": {
        "tags": [
          "commerce"
        ],
        "summary": "Commerce stack operator status (guards, sync, deprecations)",
        "operationId": "commerceStackStatus",
        "responses": {
          "200": {
            "description": "Commerce status"
          }
        },
        "description": "Processes status within the commercial subscriptions, products, financial gate, and billing domain"
      }
    },
    "/v1/subscriptions/authorize": {
      "post": {
        "tags": [
          "commerce"
        ],
        "summary": "Authorize NATS subscription with claims + billing check (GAP-C02)",
        "operationId": "authorizeSubscription",
        "responses": {
          "200": {
            "description": "NATS credential envelope"
          },
          "402": {
            "description": "Billing required"
          }
        },
        "description": "Authorizes authorize within the commercial subscriptions, products, financial gate, and billing domain"
      }
    },
    "/v1/platform/production-readiness": {
      "get": {
        "tags": [
          "platform"
        ],
        "summary": "Production readiness assessment",
        "description": "Comprehensive check of all production subsystems: Stripe, NATS, ZKP verifier, pre-verification guard, commerce guards, federation, placement config, UIC crypto, scoped signing. Returns per-subsystem status, warnings, and a top-level production_ready boolean. Use this to verify the platform is ready for live traffic.",
        "operationId": "productionReadiness",
        "responses": {
          "200": {
            "description": "Includes scoped_signing_sessions block"
          }
        }
      }
    },
    "/v1/orders": {
      "post": {
        "tags": [
          "order"
        ],
        "summary": "Create BCO order process",
        "operationId": "createOrder",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order process created"
          }
        },
        "description": "Creates a new orders within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/{processId}": {
      "get": {
        "tags": [
          "order"
        ],
        "summary": "Get order process claim",
        "operationId": "getOrderProcess",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProcessId"
          }
        ],
        "responses": {
          "200": {
            "description": "Process row"
          }
        },
        "description": "Retrieves a single processId within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/{processId}/evaluate": {
      "post": {
        "tags": [
          "order"
        ],
        "summary": "TGC rank candidates (dispatches order.candidates.score egress)",
        "operationId": "evaluateOrder",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProcessId"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked candidates + optional egress"
          }
        },
        "description": "Evaluates evaluate within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/{processId}/award": {
      "post": {
        "tags": [
          "order"
        ],
        "summary": "Award offer to process (dispatches order.award.commit egress)",
        "operationId": "awardOrder",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProcessId"
          }
        ],
        "responses": {
          "200": {
            "description": "Awarded process"
          }
        },
        "description": "Processes award within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/{processId}/orchestrate": {
      "post": {
        "tags": [
          "order"
        ],
        "summary": "Spawn billing/comms branches (dispatches order.orchestrate.enter egress)",
        "operationId": "orchestrateOrder",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProcessId"
          }
        ],
        "responses": {
          "200": {
            "description": "Orchestration result"
          }
        },
        "description": "Processes orchestrate within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/{processId}/communications/materialized": {
      "post": {
        "tags": [
          "order"
        ],
        "summary": "s37-lite bridge materialized message into order comm thread",
        "operationId": "bridgeMaterializedMessage",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProcessId"
          }
        ],
        "responses": {
          "201": {
            "description": "Message bridged"
          }
        },
        "description": "Bridges materialized within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/{processId}/communications/bridge": {
      "post": {
        "tags": [
          "order",
          "signing"
        ],
        "summary": "Bridge message into order comm thread (signing-guarded)",
        "operationId": "bridgeOrderCommunication",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProcessId"
          }
        ],
        "responses": {
          "201": {
            "description": "Message bridged"
          }
        },
        "description": "Bridges bridge within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/messages": {
      "get": {
        "tags": [
          "order",
          "signing"
        ],
        "summary": "List communication_claim messages",
        "operationId": "getCommMessages",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Message thread"
          }
        },
        "description": "Retrieves a single messages within the BCO order process graph: create, evaluate, award, orchestrate domain"
      },
      "post": {
        "tags": [
          "order",
          "signing"
        ],
        "summary": "Append signed message to comm thread",
        "operationId": "appendCommMessage",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Message appended"
          },
          "422": {
            "description": "E_SIGNING_REQUIRED"
          }
        },
        "description": "Processes messages within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/export": {
      "get": {
        "tags": [
          "order",
          "signing"
        ],
        "summary": "Export Profile A transcript bundle (or JWS/COSE views)",
        "operationId": "exportCommTranscript",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "bundle-v1",
                "jws",
                "cose"
              ],
              "default": "bundle-v1"
            }
          },
          {
            "name": "include_bodies",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include message bodies in bundle-v1 export (false → payload_hash only)"
          }
        ],
        "responses": {
          "200": {
            "description": "Transcript bundle or interop export"
          }
        },
        "description": "Exports export within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/finalize": {
      "post": {
        "tags": [
          "order",
          "signing",
          "governance"
        ],
        "summary": "Finalize high-stakes comm transcript (dual co-sign + PoCE GPR)",
        "operationId": "finalizeCommTranscript",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Idempotent — already finalized"
          },
          "201": {
            "description": "Transcript finalized"
          },
          "422": {
            "description": "Witness/cosign/bundle validation failure"
          }
        },
        "description": "Processes finalize within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/finalize/sign-dev": {
      "post": {
        "tags": [
          "order",
          "signing"
        ],
        "summary": "Dev-only: sign sov-transcript-finalize-v1 cosignature",
        "operationId": "signDevCommTranscriptFinalize",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Finalize artifact + signature (dev only)"
          },
          "404": {
            "description": "Not available in production"
          }
        },
        "description": "Signs sign dev within the BCO order process graph: create, evaluate, award, orchestrate domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/signing-session/mint": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Mint T3 context signing session",
        "operationId": "mintCommSigningSession",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Context session minted"
          }
        },
        "description": "Mints a mint within the signing domain"
      }
    },
    "/v1/orders/communications/verify-bundle": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Verify Profile A transcript bundle",
        "operationId": "verifyCommTranscriptBundle",
        "parameters": [
          {
            "name": "as_of",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Temporal validity anchor for session/delegation checks"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result"
          }
        },
        "description": "Validates and verifies verify bundle within the signing domain"
      }
    },
    "/v1/identity/signing-session/revoke": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Revoke an in-memory scoped signing session",
        "operationId": "revokeSigningSession",
        "responses": {
          "200": {
            "description": "Session revoked"
          },
          "404": {
            "description": "Session not found"
          }
        },
        "description": "Processes revoke within the signing domain"
      }
    },
    "/v1/identity/signing-session/mint": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Mint T2 daily signing session",
        "operationId": "mintDailySigningSession",
        "responses": {
          "201": {
            "description": "Daily session minted"
          }
        },
        "description": "Mints a mint within the signing domain"
      }
    },
    "/v1/identity/signing-session/verify": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Verify signed artifact",
        "operationId": "verifySigningArtifact",
        "responses": {
          "200": {
            "description": "Verification result"
          }
        },
        "description": "Validates and verifies verify within the signing domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/external/signing-session/mint": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Mint T3-external session for Profile C detached sign",
        "operationId": "mintExternalSigningSession",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "External context session minted"
          },
          "422": {
            "description": "Invalid external purpose"
          }
        },
        "description": "Mints a mint within the signing domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/external/sign-dev": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Dev-only: sign Profile C external sidecar",
        "operationId": "signDevExternalSidecar",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sidecar + optional vault record"
          },
          "404": {
            "description": "Not available in production"
          }
        },
        "description": "Signs sign dev within the signing domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/external/verify": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Verify Profile C external sidecar against payload",
        "operationId": "verifyExternalSidecar",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result"
          }
        },
        "description": "Validates and verifies verify within the signing domain"
      }
    },
    "/v1/orders/communications/{commClaimId}/external/record": {
      "post": {
        "tags": [
          "signing"
        ],
        "summary": "Verify + file external sidecar to vault (idempotent)",
        "operationId": "recordExternalSidecar",
        "parameters": [
          {
            "name": "commClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Duplicate external_id"
          },
          "201": {
            "description": "Vault claim filed"
          }
        },
        "description": "Records record within the signing domain"
      }
    },
    "/v1/governance/external/verify-detached": {
      "post": {
        "tags": [
          "signing",
          "governance"
        ],
        "summary": "Verify detached Profile C sidecar (comm id in artifact)",
        "operationId": "verifyDetachedExternalSidecar",
        "responses": {
          "200": {
            "description": "Verification result"
          }
        },
        "description": "Validates and verifies verify detached within the signing domain"
      }
    },
    "/v1/tgc/evaluate": {
      "post": {
        "tags": [
          "tgc"
        ],
        "summary": "Evaluate TGC criteria against candidate",
        "operationId": "tgcEvaluate",
        "responses": {
          "200": {
            "description": "Evaluation result"
          }
        },
        "description": "Processes evaluate within the Truth Graph Criteria matching and candidate ranking domain"
      }
    },
    "/v1/standing-orders": {
      "get": {
        "tags": [
          "standing-order"
        ],
        "summary": "List active standing orders",
        "operationId": "listStandingOrders",
        "responses": {
          "200": {
            "description": "Standing order rows"
          }
        },
        "description": "Retrieves a paginated list of standing orders within the standing-order domain"
      },
      "post": {
        "tags": [
          "standing-order"
        ],
        "summary": "Register standing order",
        "operationId": "registerStandingOrder",
        "responses": {
          "201": {
            "description": "Registered"
          }
        },
        "description": "Registers a new standing orders within the standing-order domain"
      }
    },
    "/v1/standing-orders/inventory-tick": {
      "post": {
        "tags": [
          "standing-order"
        ],
        "summary": "Push inventory update (primary standing-order trigger)",
        "operationId": "standingOrderInventoryTick",
        "responses": {
          "200": {
            "description": "Tick applied; may fire order"
          }
        },
        "description": "Processes inventory tick within the standing-order domain"
      }
    },
    "/v1/crm/pipeline/stages": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List pipeline stages by kind",
        "operationId": "listPipelineStages",
        "parameters": [
          {
            "name": "pipeline_kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. sales, support"
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline stages"
          }
        },
        "description": "Retrieves a paginated list of stages within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/pipeline/stages/{stageId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get pipeline stage by ID",
        "operationId": "getPipelineStage",
        "parameters": [
          {
            "name": "stageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline stage"
          },
          "404": {
            "description": "Stage not found"
          }
        },
        "description": "Retrieves a single stageId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/pipeline/stages/init": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Initialize default pipeline stages",
        "operationId": "initPipelineStages",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pipeline_kind",
                  "created_by"
                ],
                "properties": {
                  "pipeline_kind": {
                    "type": "string"
                  },
                  "created_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stages initialized"
          }
        },
        "description": "Processes init within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/pipeline/{pipelineKind}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List pipeline with opportunities by kind",
        "operationId": "listPipeline",
        "parameters": [
          {
            "name": "pipelineKind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline with stages and opportunities"
          }
        },
        "description": "Retrieves a paginated list of pipelineKind within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/pipeline/hooks": {
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "List registered pipeline hook handlers",
        "operationId": "listPipelineHooks",
        "responses": {
          "200": {
            "description": "List of hook handler types"
          }
        },
        "description": "Retrieves a paginated list of hooks within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/docs": {
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "Pipeline system documentation",
        "operationId": "getPipelineDocs",
        "responses": {
          "200": {
            "description": "Pipeline system documentation with endpoint listing and examples"
          }
        },
        "description": "Retrieves a single docs within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/definitions": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Register a pipeline FSM definition",
        "operationId": "registerPipelineDefinition",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineDefinition"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Definition registered"
          },
          "409": {
            "description": "Already loaded"
          },
          "422": {
            "description": "Validation error"
          }
        },
        "description": "Registers a new definitions within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      },
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "List all pipeline definitions",
        "operationId": "listPipelineDefinitions",
        "responses": {
          "200": {
            "description": "Pipeline definitions list"
          }
        },
        "description": "Retrieves a paginated list of definitions within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/definitions/{defId}": {
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "Get a pipeline definition by ID",
        "operationId": "getPipelineDefinition",
        "parameters": [
          {
            "name": "defId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline definition"
          },
          "404": {
            "description": "Not found"
          }
        },
        "description": "Retrieves a single defId within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/definitions/{defId}/load": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Load (activate) a pipeline definition",
        "operationId": "loadPipelineDefinition",
        "parameters": [
          {
            "name": "defId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "caller_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Definition loaded"
          },
          "409": {
            "description": "Already loaded"
          }
        },
        "description": "Loads load within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/instances": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Start a pipeline instance from a loaded definition",
        "description": "Creates and starts a new pipeline instance from a registered definition. Validates the definition exists and is loaded. Binds the FSM to a resource if resource_id provided. Returns the new instance_id and initial state. The instance can then be advanced via executePipelineTransition.",
        "operationId": "startPipelineInstance",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fsm_type",
                  "resource_id"
                ],
                "properties": {
                  "fsm_type": {
                    "type": "string",
                    "description": "FSM type from pipeline definition"
                  },
                  "resource_id": {
                    "type": "string",
                    "description": "Resource being processed"
                  },
                  "caller_id": {
                    "type": "string"
                  },
                  "config": {
                    "type": "object",
                    "description": "Initial binding config (e.g. poce_session_id)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pipeline instance created"
          },
          "422": {
            "description": "Validation error"
          }
        }
      },
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "List pipeline instances",
        "operationId": "listPipelineInstances",
        "parameters": [
          {
            "name": "fsm_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_active",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline instances list"
          }
        },
        "description": "Retrieves a paginated list of instances within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/instances/{bindingId}": {
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "Get pipeline instance status",
        "operationId": "getPipelineInstance",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline instance status"
          },
          "404": {
            "description": "Instance not found"
          }
        },
        "description": "Retrieves a single bindingId within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/instances/{bindingId}/transition": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Execute a pipeline stage transition",
        "operationId": "executePipelineTransition",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event"
                ],
                "properties": {
                  "event": {
                    "type": "string",
                    "description": "Transition event name (e.g. 'start', 'processed', 'approved')"
                  },
                  "payload": {
                    "type": "object",
                    "description": "Payload passed through action hooks"
                  },
                  "caller_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transition executed"
          },
          "400": {
            "description": "No matching transition"
          },
          "422": {
            "description": "Execution error"
          }
        },
        "description": "Executes transition within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/instances/{bindingId}/checkpoint": {
      "get": {
        "tags": [
          "pipeline"
        ],
        "summary": "Get current checkpoint for a pipeline instance",
        "operationId": "getPipelineCheckpoint",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Checkpoint data"
          },
          "404": {
            "description": "No checkpoint found"
          }
        },
        "description": "Retrieves a single checkpoint within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      },
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Manually save a pipeline checkpoint",
        "operationId": "savePipelineCheckpoint",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stage": {
                    "type": "string",
                    "description": "Current pipeline stage"
                  },
                  "chunk_offset": {
                    "type": "integer",
                    "default": 0
                  },
                  "status": {
                    "type": "string",
                    "default": "in_progress"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkpoint saved"
          },
          "422": {
            "description": "Save error"
          }
        },
        "description": "Saves checkpoint within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/instances/{bindingId}/resume": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Resume a pipeline from its last checkpoint",
        "operationId": "resumePipeline",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event"
                ],
                "properties": {
                  "event": {
                    "type": "string",
                    "description": "Transition event to resume with"
                  },
                  "caller_id": {
                    "type": "string"
                  },
                  "payload": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pipeline resumed"
          },
          "422": {
            "description": "Resume error"
          }
        },
        "description": "Resumes resume within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/instances/{bindingId}/ingress": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Webhook ingress for pipeline instances",
        "operationId": "pipelineIngress",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Data received and transitioned"
          },
          "202": {
            "description": "Data accepted"
          }
        },
        "description": "Processes ingress within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/pipeline/bundle": {
      "post": {
        "tags": [
          "pipeline"
        ],
        "summary": "Register + load + start a pipeline in one call",
        "operationId": "activatePipeline",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "definition",
                  "resource_id"
                ],
                "properties": {
                  "definition": {
                    "$ref": "#/components/schemas/PipelineDefinition"
                  },
                  "resource_id": {
                    "type": "string"
                  },
                  "caller_id": {
                    "type": "string"
                  },
                  "config": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pipeline activated"
          },
          "422": {
            "description": "Activation error"
          }
        },
        "description": "Activates bundle within the declarative FSM pipeline engine: definitions, instances, transitions, hooks domain"
      }
    },
    "/v1/chat/webhook/{platform}/{bindingId}": {
      "post": {
        "tags": [
          "chat"
        ],
        "summary": "Receive platform webhook message (WhatsApp, Telegram, Slack, Discord, SMS)",
        "description": "Production webhook endpoint for receiving inbound messages from any supported platform. Verifies the binding, normalizes the message via chat:inbox_ingest hook, routes through pipeline FSM, and dispatches to registered bot agents (Dify, LLM, human handoff). Supports Twilio SMS, WhatsApp Business, Telegram, Slack, and Discord formats. Returns 202 accepted.",
        "operationId": "chatWebhookIngest",
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "whatsapp",
                "telegram",
                "slack",
                "discord",
                "sms"
              ]
            },
            "description": "Platform identifier"
          },
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pipeline binding ID for the chat session"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Platform-specific webhook payload body"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message processed"
          },
          "202": {
            "description": "Message accepted for async processing"
          },
          "400": {
            "description": "Invalid signature or malformed payload"
          },
          "404": {
            "description": "Binding not found"
          }
        }
      }
    },
    "/v1/chat/health": {
      "get": {
        "tags": [
          "chat"
        ],
        "summary": "Chat subsystem health check",
        "operationId": "chatHealth",
        "responses": {
          "200": {
            "description": "Chat subsystem status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "registered_hooks": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "adapter_loaded": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Processes health within the omnichannel chat: webhook ingestion, platform adapters, bot agents, handoff domain"
      }
    },
    "/v1/crm/contacts": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Create or update a CRM contact",
        "operationId": "upsertContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contact_id",
                  "entity_id",
                  "entity_kind"
                ],
                "properties": {
                  "contact_id": {
                    "type": "string"
                  },
                  "entity_id": {
                    "type": "string"
                  },
                  "entity_kind": {
                    "type": "string"
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "lifecycle_stage": {
                    "type": "string",
                    "default": "lead"
                  },
                  "score": {
                    "type": "number",
                    "default": 0
                  },
                  "assigned_to": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Contact upserted"
          }
        },
        "description": "Creates or updates contacts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List contacts",
        "operationId": "listContacts",
        "parameters": [
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lifecycle_stage",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contact list"
          }
        },
        "description": "Retrieves a paginated list of contacts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/contacts/{contactId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get contact by ID",
        "operationId": "getContact",
        "parameters": [
          {
            "name": "contactId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contact row"
          },
          "404": {
            "description": "Contact not found"
          }
        },
        "description": "Retrieves a single contactId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/leads": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Create a CRM lead",
        "operationId": "createLead",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lead_id",
                  "created_by"
                ],
                "properties": {
                  "lead_id": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "default": "inbound"
                  },
                  "contact_id": {
                    "type": "string"
                  },
                  "company_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "current_stage": {
                    "type": "string",
                    "default": "new"
                  },
                  "assigned_to": {
                    "type": "string"
                  },
                  "priority": {
                    "type": "string",
                    "default": "medium"
                  },
                  "score": {
                    "type": "number",
                    "default": 0
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "created_by": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead created"
          }
        },
        "description": "Creates a new leads within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List leads with optional filters",
        "operationId": "listLeads",
        "parameters": [
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assigned_to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lead list"
          }
        },
        "description": "Retrieves a paginated list of leads within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/leads/{leadId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get lead by ID",
        "operationId": "getLead",
        "parameters": [
          {
            "name": "leadId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lead row"
          },
          "404": {
            "description": "Lead not found"
          }
        },
        "description": "Retrieves a single leadId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/leads/{leadId}/score": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Score a lead",
        "operationId": "scoreLead",
        "parameters": [
          {
            "name": "leadId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Score result"
          }
        },
        "description": "Scores score within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/opportunities": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Create a CRM opportunity",
        "operationId": "createOpportunity",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "opportunity_id",
                  "name",
                  "created_by"
                ],
                "properties": {
                  "opportunity_id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "contact_id": {
                    "type": "string"
                  },
                  "lead_id": {
                    "type": "string"
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number",
                    "default": 0
                  },
                  "currency": {
                    "type": "string",
                    "default": "USD"
                  },
                  "probability": {
                    "type": "number",
                    "default": 0
                  },
                  "current_stage": {
                    "type": "string",
                    "default": "discovery"
                  },
                  "pipeline_kind": {
                    "type": "string",
                    "default": "sales"
                  },
                  "assigned_to": {
                    "type": "string"
                  },
                  "expected_close_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "created_by": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Opportunity created"
          }
        },
        "description": "Creates a new opportunities within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List opportunities with optional filters",
        "operationId": "listOpportunities",
        "parameters": [
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pipeline_kind",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Opportunity list"
          }
        },
        "description": "Retrieves a paginated list of opportunities within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/opportunities/{opportunityId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get opportunity by ID",
        "operationId": "getOpportunity",
        "parameters": [
          {
            "name": "opportunityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Opportunity row"
          },
          "404": {
            "description": "Opportunity not found"
          }
        },
        "description": "Retrieves a single opportunityId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/opportunities/{opportunityId}/transition": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Transition opportunity to a new pipeline stage",
        "operationId": "transitionOpportunityStage",
        "parameters": [
          {
            "name": "opportunityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "new_stage"
                ],
                "properties": {
                  "new_stage": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transition result"
          }
        },
        "description": "Processes transition within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/interactions": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Create a CRM interaction record",
        "operationId": "createInteraction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "interaction_id",
                  "interaction_type",
                  "subject_id",
                  "subject_kind",
                  "source_subsystem"
                ],
                "properties": {
                  "interaction_id": {
                    "type": "string"
                  },
                  "interaction_type": {
                    "type": "string",
                    "enum": [
                      "email",
                      "call",
                      "meeting",
                      "note",
                      "task",
                      "system"
                    ]
                  },
                  "subject_id": {
                    "type": "string"
                  },
                  "subject_kind": {
                    "type": "string",
                    "enum": [
                      "contact",
                      "lead",
                      "opportunity",
                      "organization"
                    ]
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "source_subsystem": {
                    "type": "string"
                  },
                  "source_record_id": {
                    "type": "string"
                  },
                  "summary": {
                    "type": "string"
                  },
                  "payload": {
                    "type": "object"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Interaction created"
          }
        },
        "description": "Creates a new interactions within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List interactions by subject",
        "operationId": "listInteractions",
        "parameters": [
          {
            "name": "subject_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject_kind",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Interaction list"
          }
        },
        "description": "Retrieves a paginated list of interactions within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/interactions/{interactionId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get interaction by ID",
        "operationId": "getInteraction",
        "parameters": [
          {
            "name": "interactionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Interaction row"
          },
          "404": {
            "description": "Interaction not found"
          }
        },
        "description": "Retrieves a single interactionId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/customer-360/{entityId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get customer 360 view by entity ID",
        "operationId": "getCustomer360",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "entity_kind",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "user"
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Customer 360 payload"
          },
          "404": {
            "description": "Entity not found"
          }
        },
        "description": "Retrieves a single entityId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/cohorts": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Create a CRM cohort",
        "operationId": "createCohort",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cohort_id",
                  "name",
                  "created_by"
                ],
                "properties": {
                  "cohort_id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "filter_criteria": {
                    "type": "object"
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "created_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cohort created"
          }
        },
        "description": "Creates a new cohorts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List cohorts",
        "operationId": "listCohorts",
        "parameters": [
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cohort list"
          }
        },
        "description": "Retrieves a paginated list of cohorts within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/cohorts/{cohortId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get cohort by ID",
        "operationId": "getCohort",
        "parameters": [
          {
            "name": "cohortId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cohort row"
          },
          "404": {
            "description": "Cohort not found"
          }
        },
        "description": "Retrieves a single cohortId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/cohorts/{cohortId}/members": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List cohort members",
        "operationId": "listCohortMembers",
        "parameters": [
          {
            "name": "cohortId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Member list"
          }
        },
        "description": "Retrieves a paginated list of members within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Add entity to cohort",
        "operationId": "addToCohort",
        "parameters": [
          {
            "name": "cohortId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entity_id",
                  "entity_kind",
                  "added_by"
                ],
                "properties": {
                  "entity_id": {
                    "type": "string"
                  },
                  "entity_kind": {
                    "type": "string"
                  },
                  "added_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Member added"
          }
        },
        "description": "Processes members within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/cohorts/{cohortId}/members/{entityId}": {
      "delete": {
        "tags": [
          "crm"
        ],
        "summary": "Remove entity from cohort",
        "operationId": "removeFromCohort",
        "parameters": [
          {
            "name": "cohortId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Member removed"
          }
        },
        "description": "Processes entityId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/campaigns": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Create a CRM campaign",
        "operationId": "createCampaign",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "campaign_id",
                  "name",
                  "created_by"
                ],
                "properties": {
                  "campaign_id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "campaign_type": {
                    "type": "string",
                    "default": "email"
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "start_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "end_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "budget": {
                    "type": "number",
                    "default": 0
                  },
                  "created_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Campaign created"
          }
        },
        "description": "Creates a new campaigns within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      },
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List campaigns",
        "operationId": "listCampaigns",
        "parameters": [
          {
            "name": "organization_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign list"
          }
        },
        "description": "Retrieves a paginated list of campaigns within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/campaigns/{campaignId}": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "Get campaign by ID",
        "operationId": "getCampaign",
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign row"
          },
          "404": {
            "description": "Campaign not found"
          }
        },
        "description": "Retrieves a single campaignId within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/campaigns/{campaignId}/status": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Update campaign status",
        "operationId": "updateCampaignStatus",
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Campaign updated"
          }
        },
        "description": "Updates an existing status within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/crm/truth-graph/sync": {
      "post": {
        "tags": [
          "crm"
        ],
        "summary": "Sync a CRM entity to the truth graph",
        "operationId": "syncCrmToTruthGraph",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entity_type",
                  "entity_id"
                ],
                "properties": {
                  "entity_type": {
                    "type": "string"
                  },
                  "entity_id": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sync result"
          }
        },
        "description": "Synchronizes sync within the CRM coordination: pipeline, contacts, leads, opportunities, cohorts domain"
      }
    },
    "/v1/openapi.json": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "This OpenAPI fragment (JSON)",
        "operationId": "getOpenApiJson",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "description": "Retrieves a single openapi.json within the meta domain"
      }
    },
    "─ ─ ─ ─ Enterprise Identity (Phase 1) ─ ─ ─ ─": {},
    "/v1/enterprise/idp/{providerId}/saml": {
      "put": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Update SAML configuration for an IdP",
        "operationId": "updateIdpSamlConfig",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "saml_entity_id": {
                    "type": "string"
                  },
                  "assertion_consumer_service_url": {
                    "type": "string"
                  },
                  "saml_x509_certificate": {
                    "type": "string"
                  },
                  "saml_metadata_url": {
                    "type": "string"
                  },
                  "saml_name_id_format": {
                    "type": "string"
                  },
                  "saml_principal_attribute": {
                    "type": "string"
                  },
                  "saml_email_attribute": {
                    "type": "string"
                  },
                  "saml_group_attribute": {
                    "type": "string"
                  },
                  "saml_sign_authn_request": {
                    "type": "boolean"
                  },
                  "saml_want_assertion_signed": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SAML config updated"
          },
          "404": {
            "description": "Provider not found"
          }
        },
        "description": "Updates an existing saml within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/{providerId}/ldap": {
      "put": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Update LDAP configuration for an IdP",
        "operationId": "updateIdpLdapConfig",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ldap_url": {
                    "type": "string"
                  },
                  "ldap_base_dn": {
                    "type": "string"
                  },
                  "ldap_bind_dn": {
                    "type": "string"
                  },
                  "ldap_user_filter": {
                    "type": "string"
                  },
                  "ldap_group_filter": {
                    "type": "string"
                  },
                  "ldap_page_size": {
                    "type": "integer"
                  },
                  "ldap_connection_pool_size": {
                    "type": "integer"
                  },
                  "ldap_tls_mode": {
                    "type": "string",
                    "enum": [
                      "none",
                      "starttls",
                      "ldaps"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "LDAP config updated"
          },
          "404": {
            "description": "Provider not found"
          }
        },
        "description": "Updates an existing ldap within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/{providerId}/resolve-saml": {
      "post": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Resolve SAML assertion attributes",
        "operationId": "resolveSamlAttributes",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "saml_attributes": {
                    "type": "object",
                    "description": "SAML assertion attributes (NameID, email, groups, etc.)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved attributes"
          },
          "404": {
            "description": "Provider not found"
          }
        },
        "description": "Processes resolve saml within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/{providerId}/group-mappings": {
      "get": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "List active group→role mappings",
        "operationId": "getIdpGroupMappings",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Group mappings array"
          }
        },
        "description": "Retrieves a single group mappings within the enterprise-identity domain"
      },
      "post": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Create/update group→role mapping",
        "operationId": "mapIdpGroupToRole",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_group_name"
                ],
                "properties": {
                  "external_group_name": {
                    "type": "string"
                  },
                  "sovereign_role_key": {
                    "type": "string"
                  },
                  "sovereign_role_id": {
                    "type": "string"
                  },
                  "mapped_team_id": {
                    "type": "string"
                  },
                  "auto_provision": {
                    "type": "boolean"
                  },
                  "created_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated existing mapping"
          },
          "201": {
            "description": "Created new mapping"
          }
        },
        "description": "Processes group mappings within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/{providerId}/resolve-roles": {
      "post": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Resolve enterprise roles from IdP group memberships",
        "operationId": "resolveEnterpriseRoles",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "idp_groups": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved roles and matched groups"
          }
        },
        "description": "Processes resolve roles within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/{providerId}/health": {
      "post": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Record IdP health check result",
        "operationId": "checkIdpHealth",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "health_status": {
                    "type": "string",
                    "enum": [
                      "healthy",
                      "degraded",
                      "unreachable",
                      "unknown"
                    ]
                  },
                  "detail": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Health check recorded"
          },
          "404": {
            "description": "Provider not found"
          }
        },
        "description": "Checks health within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/{providerId}/sync": {
      "post": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Record a group sync run",
        "operationId": "recordIdpSync",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sync_type": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "groups_found": {
                    "type": "integer"
                  },
                  "users_found": {
                    "type": "integer"
                  },
                  "users_created": {
                    "type": "integer"
                  },
                  "users_updated": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sync run recorded"
          },
          "404": {
            "description": "Provider not found"
          }
        },
        "description": "Records sync within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/needing-sync": {
      "get": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Find IdPs due for group sync",
        "operationId": "listProvidersNeedingSync",
        "responses": {
          "200": {
            "description": "Providers needing sync array"
          }
        },
        "description": "Retrieves a paginated list of needing sync within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/unhealthy": {
      "get": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Find IdPs needing health attention",
        "operationId": "listUnhealthyProviders",
        "responses": {
          "200": {
            "description": "Unhealthy providers array"
          }
        },
        "description": "Retrieves a paginated list of unhealthy within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/stats": {
      "get": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Aggregated IdP statistics",
        "operationId": "getIdpStats",
        "responses": {
          "200": {
            "description": "IdP statistics object"
          }
        },
        "description": "Retrieves a single stats within the enterprise-identity domain"
      }
    },
    "/v1/enterprise/idp/group-mappings/{mappingId}": {
      "delete": {
        "tags": [
          "enterprise-identity"
        ],
        "summary": "Deactivate a group mapping",
        "operationId": "removeIdpGroupMapping",
        "parameters": [
          {
            "name": "mappingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mapping deactivated"
          },
          "404": {
            "description": "Mapping not found"
          }
        },
        "description": "Processes mappingId within the enterprise-identity domain"
      }
    },
    "─ ─ ─ ─ Identity Broker (Phase 1) ─ ─ ─ ─": {},
    "/v1/enterprise/brokers": {
      "post": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Register a new broker configuration",
        "operationId": "registerBroker",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "broker_name",
                  "broker_type",
                  "source_provider_id"
                ],
                "properties": {
                  "broker_name": {
                    "type": "string"
                  },
                  "broker_type": {
                    "type": "string",
                    "enum": [
                      "idp_federation",
                      "org_bridge",
                      "tenant_mapping",
                      "cross_realm",
                      "custom"
                    ]
                  },
                  "source_provider_id": {
                    "type": "string"
                  },
                  "target_provider_id": {
                    "type": "string"
                  },
                  "default_tenant_id": {
                    "type": "string"
                  },
                  "auto_provision": {
                    "type": "boolean"
                  },
                  "trust_sync": {
                    "type": "boolean"
                  },
                  "created_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing broker updated"
          },
          "201": {
            "description": "Broker created"
          }
        },
        "description": "Registers a new brokers within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/{brokerId}/resolve": {
      "post": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Resolve external identity to universal_claim_id",
        "operationId": "resolveIdentity",
        "parameters": [
          {
            "name": "brokerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_identity",
                  "external_org_id"
                ],
                "properties": {
                  "external_identity": {
                    "type": "string"
                  },
                  "external_org_id": {
                    "type": "string"
                  },
                  "external_email": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved identity"
          },
          "404": {
            "description": "No matching link or broker not found"
          }
        },
        "description": "Processes resolve within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/{brokerId}/links": {
      "post": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Create a manual identity broker link",
        "operationId": "createBrokerLink",
        "parameters": [
          {
            "name": "brokerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_identity",
                  "external_org_id",
                  "universal_claim_id",
                  "mapped_user_id"
                ],
                "properties": {
                  "external_identity": {
                    "type": "string"
                  },
                  "external_org_id": {
                    "type": "string"
                  },
                  "universal_claim_id": {
                    "type": "string"
                  },
                  "mapped_user_id": {
                    "type": "string"
                  },
                  "external_email": {
                    "type": "string"
                  },
                  "trust_grade": {
                    "type": "string",
                    "enum": [
                      "low",
                      "standard",
                      "elevated",
                      "high",
                      "maximum"
                    ]
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing link updated"
          },
          "201": {
            "description": "Link created"
          }
        },
        "description": "Creates a new links within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/links/{linkId}": {
      "delete": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Revoke (soft-delete) an identity broker link",
        "operationId": "revokeBrokerLink",
        "parameters": [
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Link revoked"
          },
          "404": {
            "description": "Link not found"
          }
        },
        "description": "Processes linkId within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/links/user/{universalClaimId}": {
      "get": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Get active broker links for a user",
        "operationId": "getUserBrokerLinks",
        "parameters": [
          {
            "name": "universalClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Active links array"
          }
        },
        "description": "Retrieves a single universalClaimId within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/{brokerId}/tenant/{externalOrgId}": {
      "get": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Resolve external org to sovereign tenant",
        "operationId": "resolveBrokerTenant",
        "parameters": [
          {
            "name": "brokerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "externalOrgId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant resolution"
          },
          "404": {
            "description": "No tenant mapping"
          }
        },
        "description": "Processes externalOrgId within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/{brokerId}/org-mappings": {
      "post": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Register org mapping for a broker",
        "operationId": "registerBrokerOrgMapping",
        "parameters": [
          {
            "name": "brokerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_org_id",
                  "external_org_name",
                  "mapped_org_id"
                ],
                "properties": {
                  "external_org_id": {
                    "type": "string"
                  },
                  "external_org_name": {
                    "type": "string"
                  },
                  "mapped_org_id": {
                    "type": "string"
                  },
                  "mapped_org_name": {
                    "type": "string"
                  },
                  "mapping_type": {
                    "type": "string",
                    "enum": [
                      "exact",
                      "prefix",
                      "regex",
                      "domain_suffix"
                    ]
                  },
                  "trust_level": {
                    "type": "string",
                    "enum": [
                      "federated",
                      "direct",
                      "verified",
                      "external"
                    ]
                  },
                  "created_by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing mapping updated"
          },
          "201": {
            "description": "Org mapping created"
          }
        },
        "description": "Registers a new org mappings within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/identities/{universalClaimId}": {
      "get": {
        "tags": [
          "identity-broker"
        ],
        "summary": "List external identities mapped to a universal_claim_id",
        "operationId": "getExternalIdentities",
        "parameters": [
          {
            "name": "universalClaimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "External identities array"
          }
        },
        "description": "Retrieves a single universalClaimId within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/sweep": {
      "post": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Sweep and deactivate expired broker links",
        "operationId": "sweepExpiredBrokerLinks",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sweep result with count"
          }
        },
        "description": "Processes sweep within the identity-broker domain"
      }
    },
    "/v1/enterprise/brokers/stats": {
      "get": {
        "tags": [
          "identity-broker"
        ],
        "summary": "Aggregated broker statistics",
        "operationId": "getBrokerStats",
        "responses": {
          "200": {
            "description": "Broker statistics object"
          }
        },
        "description": "Retrieves a single stats within the identity-broker domain"
      }
    },
    "─ ─ ─ ─ Identity Sync Engine (Phase 1) ─ ─ ─ ─": {},
    "/v1/enterprise/idp/sweep-sync": {
      "post": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Manual sweep of providers needing sync",
        "operationId": "sweepIdpSync",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sweep result"
          }
        },
        "description": "Processes sweep sync within the identity-sync domain"
      }
    },
    "/v1/enterprise/idp/sync/status": {
      "get": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Identity sync engine status and stats",
        "operationId": "getIdpSyncStatus",
        "responses": {
          "200": {
            "description": "Engine status and stats"
          }
        },
        "description": "Retrieves a single status within the identity-sync domain"
      }
    },
    "/v1/enterprise/idp/sweep-events": {
      "post": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Manual event consumer sweep",
        "operationId": "sweepIdpSyncEvents",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Event sweep result"
          }
        },
        "description": "Processes sweep events within the identity-sync domain"
      }
    },
    "/v1/enterprise/idp/enqueue-sync/{providerId}": {
      "post": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Enqueue sync event for a specific provider",
        "operationId": "enqueueProviderSync",
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enqueue result"
          }
        },
        "description": "Processes providerId within the identity-sync domain"
      }
    },
    "/v1/enterprise/idp/enqueue-sync-all": {
      "post": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Enqueue sync events for all active providers",
        "operationId": "enqueueAllProviderSyncs",
        "responses": {
          "200": {
            "description": "Bulk enqueue result"
          }
        },
        "description": "Processes enqueue sync all within the identity-sync domain"
      }
    },
    "/v1/enterprise/idp/sync/start": {
      "post": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Start the periodic sync consumer",
        "operationId": "startIdpSyncConsumer",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "interval_ms": {
                    "type": "integer",
                    "description": "Poll interval in ms"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Start result"
          }
        },
        "description": "Starts a new start within the identity-sync domain"
      }
    },
    "/v1/enterprise/idp/sync/stop": {
      "post": {
        "tags": [
          "identity-sync"
        ],
        "summary": "Stop the periodic sync consumer",
        "operationId": "stopIdpSyncConsumer",
        "responses": {
          "200": {
            "description": "Stop result"
          }
        },
        "description": "Stops stop within the identity-sync domain"
      }
    },
    "─ ─ ─ ─ SSO Session Management (Phase 2) ─ ─ ─ ─": {},
    "/v1/sso/sessions": {
      "post": {
        "tags": [
          "sso"
        ],
        "summary": "Create a new SSO session from a Keycloak link",
        "operationId": "createSsoSession",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "link_id",
                  "kc_user_id",
                  "realm_id"
                ],
                "properties": {
                  "link_id": {
                    "type": "string",
                    "description": "Keycloak user link ID"
                  },
                  "kc_user_id": {
                    "type": "string"
                  },
                  "realm_id": {
                    "type": "string"
                  },
                  "ttl_minutes": {
                    "type": "integer",
                    "default": 480
                  },
                  "refresh_token_hash": {
                    "type": "string"
                  },
                  "id_token_hash": {
                    "type": "string"
                  },
                  "ip_address": {
                    "type": "string"
                  },
                  "user_agent": {
                    "type": "string"
                  },
                  "kc_session_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SSO session created"
          },
          "400": {
            "description": "Invalid request or Keycloak link not found"
          }
        },
        "description": "Creates a new sessions within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    },
    "/v1/sso/sessions/{sessionId}": {
      "get": {
        "tags": [
          "sso"
        ],
        "summary": "Validate and retrieve SSO session status",
        "operationId": "validateSsoSession",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session status and validity"
          },
          "404": {
            "description": "Session not found"
          }
        },
        "description": "Processes sessionId within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    },
    "/v1/sso/sessions/{sessionId}/refresh": {
      "post": {
        "tags": [
          "sso"
        ],
        "summary": "Extend an SSO session's expiration",
        "operationId": "refreshSsoSession",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ttl_minutes": {
                    "type": "integer",
                    "default": 480
                  },
                  "refresh_token_hash": {
                    "type": "string"
                  },
                  "kc_session_state": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session refreshed"
          },
          "404": {
            "description": "Session not found"
          },
          "410": {
            "description": "Session already expired or revoked"
          }
        },
        "description": "Processes refresh within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    },
    "/v1/sso/sessions/{sessionId}/revoke": {
      "post": {
        "tags": [
          "sso"
        ],
        "summary": "Revoke an SSO session (with optional KC cascade)",
        "operationId": "revokeSsoSession",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "default": "manual_revocation"
                  },
                  "cascade_to_kc": {
                    "type": "boolean",
                    "description": "Also revoke the Keycloak user link"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session revoked"
          },
          "404": {
            "description": "Session not found"
          }
        },
        "description": "Processes revoke within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    },
    "/v1/sso/sessions/user/{subjectId}": {
      "get": {
        "tags": [
          "sso"
        ],
        "summary": "List active SSO sessions for a user",
        "operationId": "getUserSsoSessions",
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Active sessions array"
          }
        },
        "description": "Retrieves a single subjectId within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    },
    "/v1/sso/sweep": {
      "post": {
        "tags": [
          "sso"
        ],
        "summary": "Sweep and cleanup expired SSO sessions",
        "operationId": "sweepExpiredSsoSessions",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sweep result with expired and drained counts"
          }
        },
        "description": "Processes sweep within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    },
    "/v1/sso/stats": {
      "get": {
        "tags": [
          "sso"
        ],
        "summary": "SSO session statistics",
        "operationId": "getSsoStats",
        "responses": {
          "200": {
            "description": "SSO statistics object"
          }
        },
        "description": "Retrieves a single stats within the SSO session management: create, validate, refresh, revoke Keycloak sessions domain"
      }
    }
  },
  "components": {
    "parameters": {
      "ProviderId": {
        "name": "providerId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "org_ngo_kilimanjaro_aid"
        }
      },
      "ProcessId": {
        "name": "processId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "claim:process:order:abc123"
        },
        "description": "order_process claim_id"
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ValidationProblem": {
        "description": "Manifest validation failed (RFC 7807)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "GuardProblem": {
        "description": "Pre-Verification Guard rejected request",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/GuardProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "GuardProblemDetails": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ProblemDetails"
          },
          {
            "type": "object",
            "properties": {
              "s_eff": {
                "type": "number"
              },
              "s_req": {
                "type": "number"
              }
            }
          }
        ]
      },
      "ManifestListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "provider_id": {
                  "type": "string"
                },
                "manifest_id": {
                  "type": "string"
                },
                "communication_count": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "ManifestRegisterRequest": {
        "type": "object",
        "required": [
          "contract_implementations"
        ],
        "description": "Register or update a manifest. Requires at least one contract_implementation. Provider_id is canonical; re-registering updates existing manifest.",
        "properties": {
          "manifest_version": {
            "type": "string",
            "example": "2.0",
            "description": "Manifest format version. Must be '2.0' for v2 manifests."
          },
          "provider_id": {
            "type": "string",
            "description": "Unique provider identifier (e.g. 'org:gov:tz:traffic'). Used as canonical key."
          },
          "provider_name": {
            "type": "string",
            "description": "Human-readable provider name"
          },
          "implementation_context": {
            "$ref": "#/components/schemas/ImplementationContext"
          },
          "contract_implementations": {
            "type": "array",
            "description": "Contract bindings this manifest provides. Each binds a CNS contract URI to a communication type and handler.",
            "items": {
              "$ref": "#/components/schemas/ContractImplementation"
            }
          },
          "_skip_pre_verification": {
            "type": "boolean",
            "description": "Dev-only guard bypass. Never use in production."
          }
        }
      },
      "ManifestRegisterResponse": {
        "type": "object",
        "description": "Registration result with manifest details and federation sync status.",
        "properties": {
          "data": {
            "type": "object",
            "description": "Registered manifest document with provider_id, manifest_id, and binding count"
          }
        }
      },
      "ImplementationContext": {
        "type": "object",
        "required": [
          "organization_id",
          "virtual_app_id",
          "account_id"
        ],
        "description": "Context triple that uniquely identifies a manifest deployment. All three fields are required.",
        "properties": {
          "organization_id": {
            "type": "string",
            "description": "Organization colon key (e.g. 'org:gov:tz')"
          },
          "virtual_app_id": {
            "type": "string",
            "description": "Virtual app identifier within the org"
          },
          "account_id": {
            "type": "string",
            "description": "Sovereign account for billing and isolation"
          },
          "template_ref": {
            "type": "string",
            "description": "STP template reference (e.g. 'lib://tz/gov/ngo_compliance@1.0.0')"
          },
          "deployment_cell_id": {
            "type": "string",
            "description": "Target deployment cell for multi-cell routing"
          },
          "provider_id": {
            "type": "string",
            "description": "Legacy provider_id for backward compatibility"
          }
        }
      },
      "ContractImplementation": {
        "type": "object",
        "required": [
          "contract_uri",
          "communication_type"
        ],
        "description": "A single contract binding within a manifest. Maps a CNS contract URI to a communication pattern and handler.",
        "properties": {
          "contract_uri": {
            "type": "string",
            "description": "CNS contract URI (e.g. 'cns://gov/tz/traffic/sensors@v1.0.0')"
          },
          "communication_type": {
            "type": "string",
            "enum": [
              "query",
              "data_transfer",
              "dialog",
              "shared_segment",
              "subscription",
              "request"
            ],
            "description": "Communication pattern: query (request-response), data_transfer (file), dialog (multi-turn), shared_segment (real-time), subscription (feed), request (async)"
          },
          "handler": {
            "type": "string",
            "description": "Handler type: platform_default, proxy, hybrid"
          },
          "published": {
            "type": "boolean",
            "description": "Whether binding is published to federation registry"
          },
          "governance_rules": {
            "type": "object",
            "description": "Policy constraints: min_forensic_strength, zkp_gated, redaction_schema"
          },
          "streams": {
            "type": "object",
            "description": "Feed configuration: input (subscribe to feeds), output (publish events), enrichment"
          }
        }
      },
      "MembershipCreateRequest": {
        "type": "object",
        "required": [
          "membership_id",
          "user_id",
          "org_id"
        ],
        "properties": {
          "membership_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "org_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "invited",
              "active",
              "suspended",
              "left"
            ]
          }
        }
      },
      "VirtualAppCreateRequest": {
        "type": "object",
        "required": [
          "virtual_app_id",
          "org_id",
          "template_ref",
          "display_name"
        ],
        "properties": {
          "virtual_app_id": {
            "type": "string"
          },
          "org_id": {
            "type": "string"
          },
          "template_ref": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "runtime_cell_id": {
            "type": "string"
          },
          "default_account_id": {
            "type": "string"
          }
        }
      },
      "OrgApplicationProvisionRequest": {
        "type": "object",
        "required": [
          "org_name",
          "template_ref"
        ],
        "properties": {
          "org_id": {
            "type": "string"
          },
          "org_slug": {
            "type": "string"
          },
          "org_name": {
            "type": "string"
          },
          "template_ref": {
            "type": "string"
          },
          "creator_user_id": {
            "type": "string"
          },
          "deployment_cell_id": {
            "type": "string"
          }
        }
      },
      "VerifyInterfacesRequest": {
        "type": "object",
        "description": "Request to verify manifest interfaces against governance policies. Supply provider_id or context triple to scope verification.",
        "properties": {
          "provider_id": {
            "type": "string",
            "description": "Verify a specific provider's manifests"
          },
          "organization_id": {
            "type": "string",
            "description": "Verify all manifests in an organization"
          },
          "virtual_app_id": {
            "type": "string",
            "description": "Scope to a specific virtual app"
          },
          "account_id": {
            "type": "string",
            "description": "Scope to a specific sovereign account"
          },
          "contracts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Specific contract URIs to verify (empty = all)"
          },
          "include_policy_mandates": {
            "type": "boolean",
            "description": "Include governance policy mandate checks"
          },
          "project_id": {
            "type": "string",
            "description": "Project context for audit trail"
          },
          "enforce_occupancy_gate": {
            "type": "boolean",
            "description": "Enforce built-vs-approved hash gate"
          }
        }
      },
      "PolicyEvaluateRequest": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string"
          },
          "virtual_app_id": {
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "template_ref": {
            "type": "string"
          }
        }
      },
      "GuardEvaluateRequest": {
        "type": "object",
        "properties": {
          "binding": {
            "type": "object"
          },
          "payload": {
            "type": "object"
          },
          "context": {
            "type": "object"
          }
        }
      },
      "GuardEvaluateResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "allowed": {
                "type": "boolean"
              },
              "s_eff": {
                "type": "number"
              },
              "s_req": {
                "type": "number"
              },
              "score_source": {
                "type": "string",
                "enum": [
                  "aaas_factors",
                  "header",
                  "heuristic",
                  "heuristic_fallback"
                ]
              },
              "score_factors": {
                "type": "object"
              },
              "redacted": {
                "type": "boolean"
              },
              "redacted_fields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "payload": {
                "type": "object"
              }
            }
          }
        }
      },
      "VappFeedHeartbeatRequest": {
        "type": "object",
        "required": [
          "virtual_app_id",
          "source_contract_uri"
        ],
        "properties": {
          "virtual_app_id": {
            "type": "string"
          },
          "source_contract_uri": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "healthy",
              "missing",
              "degraded"
            ]
          }
        }
      },
      "OrderCreateRequest": {
        "type": "object",
        "required": [
          "buyer_id"
        ],
        "properties": {
          "buyer_id": {
            "type": "string"
          },
          "tgc_version": {
            "type": "string"
          },
          "logic": {
            "type": "string",
            "enum": [
              "and",
              "or"
            ]
          },
          "criteria": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "context": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "provider_id": {
            "type": "string",
            "description": "Manifest provider for egress hooks"
          }
        }
      },
      "PipelineDefinition": {
        "type": "object",
        "required": [
          "def_id",
          "fsm_type",
          "states",
          "transitions"
        ],
        "properties": {
          "def_id": {
            "type": "string",
            "description": "Unique definition identifier (e.g. 'supplier_quality:v1')"
          },
          "fsm_type": {
            "type": "string",
            "description": "FSM type matching fsm_definition (e.g. 'pipeline:supplier_quality:v1')"
          },
          "display_name": {
            "type": "string",
            "description": "Human-readable pipeline name"
          },
          "description": {
            "type": "string",
            "description": "Pipeline description"
          },
          "initial_state": {
            "type": "string",
            "default": "idle"
          },
          "states": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "FSM states (minimum 2)"
          },
          "transitions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PipelineTransition"
            },
            "description": "FSM transitions with optional action_hooks"
          },
          "chunked": {
            "$ref": "#/components/schemas/PipelineChunkedConfig"
          },
          "error_handling": {
            "$ref": "#/components/schemas/PipelineErrorHandling"
          }
        }
      },
      "PipelineTransition": {
        "type": "object",
        "required": [
          "from",
          "to",
          "event"
        ],
        "properties": {
          "from": {
            "type": "string",
            "description": "Source state (use '*' for wildcard)"
          },
          "to": {
            "type": "string",
            "description": "Target state"
          },
          "event": {
            "type": "string",
            "description": "Transition event name"
          },
          "display_name": {
            "type": "string"
          },
          "timeout_ms": {
            "type": "integer",
            "description": "Stage timeout in milliseconds"
          },
          "fail_hard": {
            "type": "boolean",
            "default": true,
            "description": "Whether hook failures block the transition"
          },
          "action_hooks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PipelineActionHook"
            },
            "description": "Action hooks to execute during transition"
          }
        }
      },
      "PipelineActionHook": {
        "type": "object",
        "required": [
          "hook_type"
        ],
        "properties": {
          "hook_type": {
            "type": "string",
            "description": "Hook type identifier",
            "enum": [
              "ingress:webhook",
              "queue:jetstream",
              "consume:jetstream",
              "transform:dde",
              "store:table",
              "adapter:cohort",
              "gate:criteria",
              "enrich:entity_stream",
              "emit_nats",
              "lifecycle_event",
              "iterate:cohort",
              "transform:data",
              "fork:parallel",
              "for_each:cohort",
              "poce:record",
              "poce:finalize",
              "quorum:membership",
              "quorum:status",
              "quorum:listen",
              "chat:platform_adapter",
              "chat:inbox_ingest",
              "chat:platform_send",
              "chat:human_handoff",
              "chat:enrich_context",
              "chat:bot_agent",
              "chat:llm_process"
            ]
          },
          "config": {
            "type": "object",
            "description": "Hook-specific configuration"
          },
          "timeout_ms": {
            "type": "integer",
            "description": "Per-hook timeout override (overrides transition-level timeout)"
          }
        }
      },
      "PipelineChunkedConfig": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "default": false
          },
          "chunk_size": {
            "type": "integer",
            "default": 10000,
            "description": "Items per chunk"
          },
          "checkpoint_table": {
            "type": "string",
            "default": "pipeline_checkpoint",
            "description": "SurrealDB table for checkpoint storage"
          }
        }
      },
      "PipelineErrorHandling": {
        "type": "object",
        "properties": {
          "retry_count": {
            "type": "integer",
            "default": 3
          },
          "retry_delay_ms": {
            "type": "integer",
            "default": 5000
          },
          "timeout_ms": {
            "type": "integer"
          },
          "dead_letter": {
            "type": "object",
            "properties": {
              "subject": {
                "type": "string",
                "description": "NATS subject for DLQ"
              },
              "max_retries": {
                "type": "integer",
                "default": 3
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT or dev token (dev_<username> when DEV_SKIP_AUTH=1)"
      },
      "SovereignAccountHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Sovereign-Account",
        "description": "Sovereign account ID for multi-tenant routing"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}