venue.record_live_plan_deviation

Contract

Contract version 1.6.0.
Required Agent Grant scope venue:operate.
State-affecting operation.
Input limit 65536 bytes; output limit 262144 bytes.

Input

Field	Type	Required	Default	Bounds	Meaning
deviationId	string	yes	—	min 1 chars; max 160 chars	Published contract field.
disposition	temporary \| revision-candidate	yes	—	—	Published contract field.
reasonCode	string	yes	—	min 2 chars; max 64 chars; pattern ^[A-Z][A-Z0-9_]{1,63}$	Published contract field.
location	object \| object	yes	—	—	Published contract field.
affectedObjectIds	string[]	yes	—	min 1 items; max 100 items; unique items	Published contract field.
availableConstraintIds	string[]	yes	—	min 1 items; max 100 items; unique items	Published contract field.
change	object	yes	—	—	Published contract field.
idempotencyKey	string	yes	—	min 1 chars	Unique retry key for this semantic command.
correlationId	string	no	—	min 1 chars	Optional caller correlation identifier.

json

{
  "deviationId": "deviation-east-exit-control",
  "disposition": "temporary",
  "reasonCode": "LIVE_EGRESS_CONTROL",
  "location": {
    "kind": "plan-object",
    "planObjectId": "obj-fire-exit-east"
  },
  "affectedObjectIds": [
    "obj-fire-exit-east"
  ],
  "availableConstraintIds": [
    "constraint-emergency-readiness",
    "constraint-peak-congestion"
  ],
  "change": {
    "id": "change-live-egress-control",
    "targetObjectIds": [
      "obj-fire-exit-east"
    ],
    "spatialEffects": [
      {
        "operation": "update_metadata",
        "objectId": "obj-fire-exit-east",
        "values": {
          "label": "East exit — controlled"
        }
      }
    ]
  },
  "idempotencyKey": "example-deviation-record-001"
}

Output

An idempotent operational fact that preserves the approved Plan and records live Constraint results.

Output field	Meaning
register	Published result field.
deviation	Published result field.
overlay	Published result field.
receipt	Published result field.
duplicate	Published result field.

Stable ID: register.id
Stable ID: deviation.id
Stable ID: overlay.id
Stable ID: receipt.id

Errors

Code	Message	Remediation
TOOL_SCOPE_REQUIRED	Tool authorization scope is required.	Grant the published scope for this tool or use a read-only tool within the current session.
AUTHORIZATION_DENIED	The current principal is not authorized for this VenueMind action.	Use an assigned Organization Membership Role or an active Organization- and Project-scoped Agent Grant containing the required permission.
AGENT_GRANT_INVALID	Agent Grant is invalid.	Issue a complete Organization- and Project-scoped grant with published scopes and a lifetime of one hour or less.
TOOL_PAYLOAD_TOO_LARGE	Tool payload exceeds its published size limit.	Reduce the requested geometry or export payload and retry within the published byte limit.
TOOL_CALL_CANCELLED	Tool call was cancelled.	Retry only if the caller still needs the operation, using the same idempotency key for an interrupted mutation.
VENUE_INTERNAL_ERROR	VenueMind could not complete the operation.	Retry once; if the error persists, inspect the server log with the correlation ID.
IDEMPOTENCY_KEY_REQUIRED	Idempotency key is required for mutating commands.	Retry with one stable idempotency key for this semantic action.
IDEMPOTENCY_KEY_CONFLICT	Idempotency key conflict.	Use the original command input or generate a new idempotency key.
DEVIATION_REGISTER_NOT_FOUND	Live Plan Deviation Register is unavailable.	Create the register from the active Event Day Runbook before inspecting or recording deviations.
DEVIATION_NOT_FOUND	Live Plan Deviation is unavailable.	Inspect the register and retry with an existing stable Deviation ID.
DEVIATION_TOOL_UNAVAILABLE	Live Plan Deviation tool Adapter is unavailable.	Open VenueMind Studio or connect an MCP Project session with Live Plan Deviation operations enabled.
DEVIATION_INVALID	Live Plan Deviation input is invalid.	Supply a reason code, disposition, exact affected objects, location, and executable spatial Change.
DEVIATION_LOCATION_INVALID	Live Plan Deviation Location Context is invalid.	Anchor the deviation to one object or in-room coordinate in the frozen accepted Plan.
DEVIATION_REVISION_CONFLICT	Live Plan Deviation revision conflict.	Refresh the deviation projection and retry only if the transition is still required.
DEVIATION_REGISTER_REVISION_CONFLICT	Live Plan Deviation Register revision conflict.	Refresh the active overlay and retry against its current revision.
DEVIATION_LEDGER_INTEGRITY_FAILED	Live Plan Deviation ledger integrity failed.	Restore the last verified register state before inspection, recommendation, or export.

Surfaces

WebMCP runtime Standalone MCP Complete error catalog

Input

Field	Type	Required	Default	Bounds	Meaning
deviationId	string	yes	—	min 1 chars; max 160 chars	Published contract field.
disposition	temporary \| revision-candidate	yes	—	—	Published contract field.
reasonCode	string	yes	—	min 2 chars; max 64 chars; pattern ^[A-Z][A-Z0-9_]{1,63}$	Published contract field.
location	object \| object	yes	—	—	Published contract field.
affectedObjectIds	string[]	yes	—	min 1 items; max 100 items; unique items	Published contract field.
availableConstraintIds	string[]	yes	—	min 1 items; max 100 items; unique items	Published contract field.
change	object	yes	—	—	Published contract field.
idempotencyKey	string	yes	—	min 1 chars	Unique retry key for this semantic command.
correlationId	string	no	—	min 1 chars	Optional caller correlation identifier.

json

{
  "deviationId": "deviation-east-exit-control",
  "disposition": "temporary",
  "reasonCode": "LIVE_EGRESS_CONTROL",
  "location": {
    "kind": "plan-object",
    "planObjectId": "obj-fire-exit-east"
  },
  "affectedObjectIds": [
    "obj-fire-exit-east"
  ],
  "availableConstraintIds": [
    "constraint-emergency-readiness",
    "constraint-peak-congestion"
  ],
  "change": {
    "id": "change-live-egress-control",
    "targetObjectIds": [
      "obj-fire-exit-east"
    ],
    "spatialEffects": [
      {
        "operation": "update_metadata",
        "objectId": "obj-fire-exit-east",
        "values": {
          "label": "East exit — controlled"
        }
      }
    ]
  },
  "idempotencyKey": "example-deviation-record-001"
}

Output

An idempotent operational fact that preserves the approved Plan and records live Constraint results.

Output field	Meaning
register	Published result field.
deviation	Published result field.
overlay	Published result field.
receipt	Published result field.
duplicate	Published result field.

Stable ID: register.id

Stable ID: deviation.id

Stable ID: overlay.id

Stable ID: receipt.id

Errors

Code	Message	Remediation
TOOL_SCOPE_REQUIRED	Tool authorization scope is required.	Grant the published scope for this tool or use a read-only tool within the current session.
AUTHORIZATION_DENIED	The current principal is not authorized for this VenueMind action.	Use an assigned Organization Membership Role or an active Organization- and Project-scoped Agent Grant containing the required permission.
AGENT_GRANT_INVALID	Agent Grant is invalid.	Issue a complete Organization- and Project-scoped grant with published scopes and a lifetime of one hour or less.
TOOL_PAYLOAD_TOO_LARGE	Tool payload exceeds its published size limit.	Reduce the requested geometry or export payload and retry within the published byte limit.
TOOL_CALL_CANCELLED	Tool call was cancelled.	Retry only if the caller still needs the operation, using the same idempotency key for an interrupted mutation.
VENUE_INTERNAL_ERROR	VenueMind could not complete the operation.	Retry once; if the error persists, inspect the server log with the correlation ID.
IDEMPOTENCY_KEY_REQUIRED	Idempotency key is required for mutating commands.	Retry with one stable idempotency key for this semantic action.
IDEMPOTENCY_KEY_CONFLICT	Idempotency key conflict.	Use the original command input or generate a new idempotency key.
DEVIATION_REGISTER_NOT_FOUND	Live Plan Deviation Register is unavailable.	Create the register from the active Event Day Runbook before inspecting or recording deviations.
DEVIATION_NOT_FOUND	Live Plan Deviation is unavailable.	Inspect the register and retry with an existing stable Deviation ID.
DEVIATION_TOOL_UNAVAILABLE	Live Plan Deviation tool Adapter is unavailable.	Open VenueMind Studio or connect an MCP Project session with Live Plan Deviation operations enabled.
DEVIATION_INVALID	Live Plan Deviation input is invalid.	Supply a reason code, disposition, exact affected objects, location, and executable spatial Change.
DEVIATION_LOCATION_INVALID	Live Plan Deviation Location Context is invalid.	Anchor the deviation to one object or in-room coordinate in the frozen accepted Plan.
DEVIATION_REVISION_CONFLICT	Live Plan Deviation revision conflict.	Refresh the deviation projection and retry only if the transition is still required.
DEVIATION_REGISTER_REVISION_CONFLICT	Live Plan Deviation Register revision conflict.	Refresh the active overlay and retry against its current revision.
DEVIATION_LEDGER_INTEGRITY_FAILED	Live Plan Deviation ledger integrity failed.	Restore the last verified register state before inspection, recommendation, or export.