Governance Contracts

Governance contracts are the foundational primitive for workspace-to-workspace communication in Roundtable. Every bridge that carries real traffic must have an active contract governing it. A contract is a typed, cryptographically-enforced agreement that precisely specifies which actions one workspace may take toward another.

What a Contract Does

Defines which actions the source workspace may invoke on the target
Requires explicit approval from both workspace admins before any traffic is permitted
Is self-reinforcing: the control plane embeds a contract token (HMAC of the contract's terms) in every bridge request, and the target pod re-derives and verifies it independently
Governs amendments: proposed changes are staged and unenforced until both parties re-approve

Built-in Contract Types

Each type carries a set of pre-defined action presets. You can deselect any preset action or add custom ones.

General

Field	Value
Preset Actions	`message`, `delegate`
Typical Use	General-purpose cross-workspace AI communication

MedicationRequest

Field	Value
Preset Actions	`request_medication_review`, `check_inventory`, `flag_interaction`, `request_formulary_check`
Typical Source	Pharmacy, Clinical Decision Support
Typical Target	ICU, Emergency, Inpatient
Compliance	HIPAA, Joint Commission

PatientHandoff

Field	Value
Preset Actions	`transfer_patient`, `request_bed`, `send_summary`, `escalate_acuity`
Typical Use	Patient transfer coordination across clinical units

ClinicalEscalation

Field	Value
Preset Actions	`escalate_critical`, `request_consult`, `flag_deterioration`, `request_rapid_response`
Typical Use	Critical finding escalation and rapid response activation

FinancialReport

Field	Value
Preset Actions	`request_cost_analysis`, `query_revenue`, `request_budget_review`, `flag_variance`
Typical Use	Cross-department financial reporting and variance flagging

DataQuery

Field	Value
Preset Actions	`query_census`, `query_metrics`, `query_outcomes`, `request_report`
Typical Use	Read-only access to another workspace's data connections

McpToolAccess

Field	Value
Preset Actions	`tools_list`, `tools_call`, `resources_read`, `resources_list`
Typical Use	Calling specific MCP tools exposed by another workspace

AgentDelegation

Field	Value
Preset Actions	`message_send`, `tasks_get`, `tasks_cancel`, `stream_subscribe`
Typical Use	Delegating tasks to an A2A-compatible agent in another workspace

Custom Contract Types

Organizations can define custom types that map to their own governance requirements. Specify a descriptive name (e.g., TradeExecution, IncidentEscalation, SupplyChainRequest) and define the allowed actions explicitly.

Custom types inherit full cryptographic enforcement automatically.

Contract Fields

Field	Description
`type`	Contract type (built-in or custom)
`sourceWsId`	The workspace initiating actions
`targetWsId`	The workspace receiving actions
`allowedActions`	Exact list of permitted action identifiers
`escalationTarget`	Workspace to route unresolvable actions to (optional)
`expiresAt`	Date after which the contract auto-expires (optional)
`requires`	Additional workspace IDs that must also approve (optional)

Contract Lifecycle

  Created          Pending Approval          Active
     │                    │                    │
     ▼                    ▼                    ▼
 ┌────────┐    ┌──────────────────┐    ┌───────────┐
 │ Draft  │───▶│ pending_approval │───▶│  active   │────┐
 └────────┘    └──────────────────┘    └─────┬─────┘    │
                                             │          │ Material
                                             │ Suspend  │ change
                                             ▼          │ proposed
                                      ┌───────────┐     │
                                      │ suspended │     ▼
                                      └───────────┘  ┌─────────────────┐
                                                      │ pending_        │
                                                      │ amendment       │◀─ original terms
                                                      │ (still active)  │   still enforced
                                                      └────────┬────────┘
                                                               │ Both admins re-approve
                                                               ▼
                                                        ┌───────────┐
                                                        │  active   │
                                                        │ (new terms)│
                                                        └───────────┘

Status Reference

Status	Traffic Permitted	Description
`draft`	❌	Contract created but not yet submitted for approval
`pending_approval`	❌	Awaiting approval from one or both workspace admins
`active`	✅	Fully approved and enforced
`pending_amendment`	✅ (old terms)	A material change is proposed but not yet re-approved — original terms remain enforced
`suspended`	❌	Manually suspended by an admin
`expired`	❌	Passed the `expiresAt` date

The Handshake Approval Model

Contracts require explicit approval from both workspace admins — one for the source workspace and one for the target. This is a two-party handshake, not a unilateral grant.

A workspace admin creates a contract via the Contract Builder wizard (Governance → + New Contract).
The contract enters pending_approval — no traffic is permitted.
An admin of the source workspace approves their side.
An admin of the target workspace approves their side.
Once both sides are approved, the contract becomes active and the bridge is enforced.

:::info Single-owner organizations If one person administers both workspaces, they can approve both sides — but they must do so as two explicit acts, one for each workspace. This ensures the approval intent is always recorded per workspace. :::

Amendment Flow

When an active contract needs to change, a workspace admin proposes an amendment. The key design principle: original terms remain enforced while the amendment is pending.

This means:

Existing bridge traffic continues uninterrupted
The proposed new allowedActions (or other material fields) are staged in amendment.proposedChanges, not applied
Both workspace admins must re-approve the amendment before the new terms take effect
If someone fraudulently attempts to add an action, that action sits in proposedChanges (unenforced) until the other workspace admin explicitly approves it

Material vs. Non-Material Changes

Material changes (require re-approval from both admins):

allowedActions — adding or removing permitted actions
type — changing the contract type
escalationTarget — changing where failures are routed
requires — changing additional approval requirements

Non-material changes (take effect immediately, no re-approval):

expiresAt — adjusting the expiration date
name / display fields

Amendment Lifecycle

1. Admin proposes change (PATCH /contracts/:id)
   → Contract status: pending_amendment
   → amendment.proposedChanges = { allowedActions: [...new set...] }
   → amendment.sourceReApproved = false, targetReApproved = false
   → Live contract fields UNCHANGED — original terms still enforced

2. Source workspace admin re-approves
   → amendment.sourceReApproved = true

3. Target workspace admin re-approves
   → amendment.targetReApproved = true
   → proposedChanges applied to contract document
   → amendment sub-document deleted
   → Contract status: active (new terms)

Creating and Editing Contracts

Creating a New Contract

Go to Governance → + New Contract. The Contract Builder wizard guides you through four steps:

Route — Choose the source and target workspaces. Direction is fixed once created.
Actions — Select a contract type and pick allowed actions. Preset actions include descriptions; you can also add custom action identifiers.
Constraints — Optionally set an escalation target, expiration date, or prerequisite contracts.
Review — See a natural-language summary and confirm. After creation, both workspace admins will need to approve.

Editing an Existing Contract

Click the ✏️ edit button on any contract row in the Governance table. The same Contract Builder wizard opens, pre-populated with current values and starting on the Actions step (route is read-only for existing contracts).

The wizard shows a live diff of your changes vs. the current contract — green additions, red strikethrough removals. The Submit button adapts based on whether your changes are material:

No material change → Save Changes (takes effect immediately)
Material change → Propose Amendment (triggers re-approval flow)

HMAC Enforcement

Every bridge request is cryptographically validated end-to-end:

Control Plane (dispatch)

When the control plane relays a bridge request, it:

Looks up the active (or pending_amendment) contract for the source→target direction
Verifies the requested action is in allowedActions — rejects if not
Generates a contractToken: HMAC-SHA256(BRIDGE_HMAC_SECRET, contractId:sortedAllowedActions)
Signs the request: HMAC-SHA256(secret, taskId:timestamp:contractId:action)
Attaches an X-Contract-Action header carrying the signed action name (e.g. message_send, discover, query:query_bigquery)
Forwards contractId, contractToken, the X-Contract-Action header, and the extended signature to the target pod

Target Pod (receive)

The pod's bridge receive handler enforces a five-stage gate:

HMAC + timestamp — Verifies the request signature and rejects requests older than 5 minutes
X-Contract-Action verification — The auth middleware reads the X-Contract-Action header and verifies the HMAC was signed against this action. For backward compatibility, requests without the header default to message_send
Contract existence — contractId must exist in the local RT_CONTRACTS manifest (CONTRACT_NOT_FOUND → 403)
Contract token — Pod re-derives HMAC(contractId:sortedAllowedActions) from its local manifest and compares with timingSafeEqual (CONTRACT_TOKEN_INVALID → 403)
Action check — Requested action must be in the local manifest's allowedActions (ACTION_NOT_PERMITTED → 403)

This makes enforcement self-reinforcing: even if a request somehow bypassed the control plane check, the pod would reject it because it independently re-derives the contract token from its own copy of the manifest.

:::warning Tampering detection If anyone modifies allowedActions in transit, the contract token comparison fails at stage 4. The pod never reaches stage 5. The original allowed-action set is cryptographically bound into the token using the shared symmetric key. :::

Strict Action Enforcement

Not all actions are treated equally. Roundtable distinguishes between transport actions that are intrinsic to the bridge protocol and intent operations that access workspace capabilities.

Transport Actions (Auto-Allowed)

The following five protocol-level actions are automatically permitted for any active contract — they do not need to appear in allowedActions:

Action	Purpose
`message`	General bridge messaging
`delegate`	Task delegation
`message_send`	A2A message dispatch
`tasks_get`	Query delegated task status
`tasks_cancel`	Cancel a delegated task

These are the minimum operations required for two workspaces to exchange bridge traffic under their contract.

Intent Operations (Explicit Listing Required)

All other actions — including discovery, queries, tool invocations, capability calls, and aggregations — must be explicitly listed in the contract's allowedActions. There is no wildcard bypass.

Examples of intent operations that require explicit listing:

discover — Workspace capability discovery
query:query_bigquery — Named data queries
tool:read_file — MCP tool invocations
capability:risk.calculateVar — Typed capability calls
aggregate — Cross-workspace aggregation

Example `allowedActions`

["message", "delegate", "signal_transfer", "discover", "query:query_bigquery"]

In this example, message and delegate are transport actions (auto-allowed regardless), while signal_transfer, discover, and query:query_bigquery are intent operations that must be explicitly listed or the pod will reject them at stage 5 of the enforcement gate.

What a Contract Does​

Built-in Contract Types​

General​

MedicationRequest​

PatientHandoff​

ClinicalEscalation​

FinancialReport​

DataQuery​

McpToolAccess​

AgentDelegation​

Custom Contract Types​

Contract Fields​

Contract Lifecycle​

Status Reference​

The Handshake Approval Model​

Amendment Flow​

Material vs. Non-Material Changes​

Amendment Lifecycle​

Creating and Editing Contracts​

Creating a New Contract​

Editing an Existing Contract​

HMAC Enforcement​

Control Plane (dispatch)​

Target Pod (receive)​

Strict Action Enforcement​

Transport Actions (Auto-Allowed)​

Intent Operations (Explicit Listing Required)​

Example allowedActions​