{
  "$schema": "../schemas/tool-detail.schema.json",
  "formatVersion": "roslyn-workbench-tool-reference/v1",
  "productVersion": "1.0.1",
  "sourceTag": "1.0.1",
  "commit": "b2b132afacb169d16deead9fc88253213a942b25",
  "name": "transaction-commit",
  "title": "Transaction Commit",
  "area": "Server",
  "category": "Transactions",
  "operationKind": "Mutation",
  "summary": "Commits the active transaction. Transactional and autonomous-trusted modes use the standard request; approval-required mode requires a transaction-review receipt and requests one-use approval for that exact change.",
  "availability": "Published in transactional, approval-required and autonomous-trusted operational modes.",
  "documentationUrl": "https://lantean-code.github.io/roslyn-workbench-mcp/1.0.1/reference/tools/transaction-commit.html",
  "tool": {
    "name": "transaction-commit",
    "title": "Transaction Commit",
    "description": "Commits the active transaction. Transactional and autonomous-trusted modes use the standard request; approval-required mode requires a transaction-review receipt and requests one-use approval for that exact change.",
    "inputSchema": {
      "type": "object",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "expectedSnapshot": {
              "type": "object",
              "properties": {
                "workspaceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "workspaceEpoch": {
                  "type": "integer"
                },
                "snapshotId": {
                  "type": "string",
                  "format": "uuid"
                },
                "transactionRevision": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              },
              "required": [
                "workspaceId",
                "workspaceEpoch",
                "snapshotId",
                "transactionRevision"
              ],
              "description": "Echo the snapshot returned with the data or transaction state used to construct this request."
            },
            "workspace": {
              "description": "Provide workspaceId, alias, path, or any combination.",
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "workspaceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "alias": {
                  "type": "string"
                },
                "path": {
                  "description": "Absolute workspace path.",
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "expectedSnapshot"
          ],
          "title": "Transactional and autonomous-trusted request"
        },
        {
          "type": "object",
          "properties": {
            "receiptId": {
              "description": "The opaque receipt identifier returned by transaction-review.",
              "type": "string",
              "minLength": 1
            },
            "expectedSnapshot": {
              "type": "object",
              "properties": {
                "workspaceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "workspaceEpoch": {
                  "type": "integer"
                },
                "snapshotId": {
                  "type": "string",
                  "format": "uuid"
                },
                "transactionRevision": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              },
              "required": [
                "workspaceId",
                "workspaceEpoch",
                "snapshotId",
                "transactionRevision"
              ],
              "description": "Echo the snapshot returned with the data or transaction state used to construct this request."
            },
            "workspace": {
              "description": "Provide workspaceId, alias, path, or any combination.",
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "workspaceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "alias": {
                  "type": "string"
                },
                "path": {
                  "description": "Absolute workspace path.",
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "receiptId",
            "expectedSnapshot"
          ],
          "title": "Approval-required receipt request"
        }
      ]
    },
    "outputSchema": {
      "type": "object",
      "oneOf": [
        {
          "type": "object",
          "required": [
            "ok",
            "data"
          ],
          "properties": {
            "ok": {
              "const": true,
              "description": "Whether the tool invocation succeeded."
            },
            "data": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "committed": {
                  "description": "Whether the commit succeeded.",
                  "type": "boolean"
                },
                "transaction": {
                  "description": "The final transaction info, when available.",
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "revision": {
                      "description": "Current staged transaction revision.",
                      "type": "integer"
                    },
                    "revisionCount": {
                      "description": "Number of revisions retained in transaction history.",
                      "type": "integer"
                    },
                    "maxRevisions": {
                      "description": "Maximum number of revisions the transaction can retain.",
                      "type": "integer"
                    },
                    "remainingRevisions": {
                      "description": "Number of additional revisions that can be staged.",
                      "type": "integer"
                    },
                    "canMutate": {
                      "description": "Whether mutation tools may stage another change.",
                      "type": "boolean"
                    },
                    "canUndo": {
                      "description": "Whether transaction history can move to the preceding revision.",
                      "type": "boolean"
                    },
                    "canRedo": {
                      "description": "Whether transaction history can move to the following revision.",
                      "type": "boolean"
                    },
                    "canCommit": {
                      "description": "Whether the staged transaction can be committed to disk.",
                      "type": "boolean"
                    },
                    "canRollback": {
                      "description": "Whether the complete staged transaction can be discarded.",
                      "type": "boolean"
                    }
                  }
                }
              },
              "description": "Tool-specific result payload."
            },
            "snapshot": {
              "type": "object",
              "properties": {
                "workspaceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "workspaceEpoch": {
                  "type": "integer"
                },
                "snapshotId": {
                  "type": "string",
                  "format": "uuid"
                },
                "transactionRevision": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              },
              "required": [
                "workspaceId",
                "workspaceEpoch",
                "snapshotId",
                "transactionRevision"
              ],
              "description": "Exact immutable workspace snapshot associated with the result, when available."
            },
            "warnings": {
              "type": "array",
              "description": "Non-fatal warnings the agent should consider.",
              "items": {
                "$ref": "#/$defs/warningInfo"
              }
            }
          }
        },
        {
          "type": "object",
          "required": [
            "ok",
            "error"
          ],
          "properties": {
            "ok": {
              "const": false,
              "description": "Whether the tool invocation succeeded."
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "description": "Stable machine-readable error code.",
                  "type": "string"
                },
                "message": {
                  "description": "Human-readable explanation of the failure.",
                  "type": "string"
                },
                "correlationId": {
                  "description": "Correlation identifier for matching the failure to server-side diagnostics, when available.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "code",
                "message"
              ],
              "description": "Structured error details when the invocation failed."
            },
            "continuation": {
              "oneOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "tool",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "CallTool",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    },
                    "tool": {
                      "type": "string",
                      "description": "Tool to call before continuing the original request.",
                      "minLength": 1
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "tools",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "ChooseTool",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    },
                    "tools": {
                      "type": "array",
                      "description": "Allowed tool choices from which the agent must select one.",
                      "minItems": 1,
                      "uniqueItems": true,
                      "items": {
                        "type": "string",
                        "description": "Name of a tool the agent may choose.",
                        "minLength": 1
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "RetryRequest",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "ReviseRequest",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    }
                  }
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "instruction"
                  ],
                  "properties": {
                    "kind": {
                      "const": "ResolveExternally",
                      "description": "Action required before the original request can continue."
                    },
                    "instruction": {
                      "type": "string",
                      "description": "Agent-facing instruction explaining how to continue.",
                      "minLength": 1
                    }
                  }
                }
              ],
              "description": "Action the agent should take before retrying or continuing."
            },
            "diagnostics": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "description": "The diagnostic identifier.",
                    "type": "string"
                  },
                  "severity": {
                    "description": "The diagnostic severity.",
                    "type": "string",
                    "enum": [
                      "Hidden",
                      "Info",
                      "Warning",
                      "Error"
                    ]
                  },
                  "message": {
                    "description": "The diagnostic message.",
                    "type": "string"
                  },
                  "location": {
                    "description": "The optional source location of the diagnostic.",
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "document": {
                        "description": "The resolved document.",
                        "type": [
                          "object",
                          "null"
                        ],
                        "properties": {
                          "documentId": {
                            "description": "The document identifier.",
                            "type": "string"
                          },
                          "path": {
                            "description": "The normalized document path.",
                            "type": "string"
                          },
                          "projectId": {
                            "description": "The owning project identifier.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "documentId",
                          "path",
                          "projectId"
                        ]
                      },
                      "span": {
                        "description": "The resolved text span.",
                        "type": [
                          "object",
                          "null"
                        ],
                        "properties": {
                          "start": {
                            "description": "Zero-based UTF-16 offset.",
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 2147483647
                          },
                          "length": {
                            "description": "UTF-16 code-unit length.",
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 2147483647
                          }
                        }
                      },
                      "line": {
                        "description": "The one-based line number.",
                        "type": "integer"
                      },
                      "column": {
                        "description": "The one-based column number.",
                        "type": "integer"
                      },
                      "snapshot": {
                        "description": "The exact immutable workspace snapshot associated with this location.",
                        "type": "object",
                        "properties": {
                          "workspaceId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "workspaceEpoch": {
                            "type": "integer"
                          },
                          "snapshotId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "transactionRevision": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "workspaceId",
                          "workspaceEpoch",
                          "snapshotId",
                          "transactionRevision"
                        ]
                      },
                      "selector": {
                        "description": "The canonical selector that can resolve this source location again.",
                        "type": [
                          "object",
                          "null"
                        ],
                        "properties": {
                          "span": {
                            "type": "object",
                            "properties": {
                              "document": {
                                "description": "Provide exactly one of path or documentId.",
                                "type": "object",
                                "properties": {
                                  "project": {
                                    "description": "Disambiguates documents with matching paths or IDs.",
                                    "type": [
                                      "object",
                                      "null"
                                    ],
                                    "properties": {
                                      "projectId": {
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "name": {
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "path": {
                                        "description": "Workspace-relative path.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "targetFramework": {
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      }
                                    }
                                  },
                                  "path": {
                                    "description": "Workspace-relative path.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "documentId": {
                                    "description": "Workspace-local document ID.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                }
                              },
                              "range": {
                                "description": "Zero-based UTF-16 range.",
                                "type": "object",
                                "properties": {
                                  "start": {
                                    "description": "Zero-based UTF-16 offset.",
                                    "type": "integer",
                                    "minimum": 0,
                                    "maximum": 2147483647
                                  },
                                  "length": {
                                    "description": "UTF-16 code-unit length.",
                                    "type": "integer",
                                    "minimum": 0,
                                    "maximum": 2147483647
                                  }
                                }
                              }
                            },
                            "required": [
                              "document",
                              "range"
                            ]
                          }
                        },
                        "required": [
                          "span"
                        ]
                      }
                    },
                    "required": [
                      "snapshot"
                    ]
                  }
                },
                "required": [
                  "id",
                  "message"
                ]
              },
              "description": "Diagnostics that explain the failed invocation."
            },
            "warnings": {
              "type": "array",
              "description": "Non-fatal warnings the agent should consider.",
              "items": {
                "$ref": "#/$defs/warningInfo"
              }
            }
          }
        },
        {
          "type": "object",
          "required": [
            "ok",
            "error",
            "diagnostics"
          ],
          "properties": {
            "ok": {
              "const": false,
              "description": "Whether the tool invocation succeeded."
            },
            "error": {
              "type": "object",
              "required": [
                "code",
                "message",
                "correlationId"
              ],
              "properties": {
                "code": {
                  "const": "UnhandledException"
                },
                "message": {
                  "const": "Tool execution failed."
                },
                "correlationId": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "description": "Structured error details when the invocation failed."
            },
            "diagnostics": {
              "type": "object",
              "required": [
                "detailsAvailable",
                "detailsTool"
              ],
              "properties": {
                "detailsAvailable": {
                  "const": true
                },
                "detailsTool": {
                  "const": "get-error-details"
                }
              },
              "description": "Diagnostics that explain the failed invocation."
            },
            "reporting": {
              "type": "object",
              "properties": {
                "state": {
                  "type": "string",
                  "enum": [
                    "Available",
                    "AlwaysApproved",
                    "DisabledByConfiguration",
                    "ApprovalUnavailable"
                  ]
                },
                "canPrepare": {
                  "type": "boolean"
                },
                "prepareTool": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "state"
              ],
              "description": "Error-reporting workflow available for an unhandled failure."
            }
          }
        }
      ],
      "$defs": {
        "warningInfo": {
          "type": "object",
          "properties": {
            "code": {
              "description": "The stable machine-readable warning code.",
              "type": "string"
            },
            "message": {
              "description": "The human-readable warning message.",
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ]
        }
      }
    },
    "annotations": {
      "title": "Transaction Commit",
      "destructiveHint": true,
      "idempotentHint": false,
      "openWorldHint": false,
      "readOnlyHint": false
    }
  },
  "examples": [
    {
      "operationalModes": [
        "transactional",
        "autonomous-trusted"
      ],
      "workflowId": "transaction-change",
      "workflowTitle": "Stage, review and commit one change",
      "step": 4,
      "id": "commit-transaction",
      "title": "Commit the reviewed snapshot",
      "purpose": "Write the staged files only when the transaction still matches the previewed snapshot.",
      "expectedOutcome": "The commit succeeds only if the supplied snapshot still identifies the current staged revision.",
      "representativeResponse": {
        "ok": false,
        "error": {
          "code": "SnapshotMismatch",
          "message": "The staged transaction no longer matches the expected snapshot."
        },
        "continuation": {
          "kind": "CallTool",
          "tool": "transaction-preview",
          "instruction": "Preview the current staged revision and ask the user to review it before committing."
        }
      },
      "request": {
        "expectedSnapshot": {
          "workspaceId": "11111111-1111-1111-1111-111111111111",
          "workspaceEpoch": 1,
          "snapshotId": "22222222-2222-2222-2222-222222222222",
          "transactionRevision": 1
        },
        "workspace": {
          "alias": "sample"
        }
      }
    },
    {
      "operationalModes": [
        "approval-required"
      ],
      "workflowId": "receipt-approved-change",
      "workflowTitle": "Review an exact change for one-use approval",
      "step": 4,
      "id": "commit-reviewed-receipt",
      "title": "Approve and commit the exact receipt",
      "purpose": "Request one-use user approval and persist only the exact change represented by the current receipt.",
      "expectedOutcome": "The Host confirms the receipt is current, elicits approval, revalidates the exact persistence identity and writes the staged source files.",
      "representativeResponse": null,
      "request": {
        "receiptId": "4d5b5f7df39e4dd6a6ed9707f927aefa",
        "expectedSnapshot": {
          "workspaceId": "11111111-1111-1111-1111-111111111111",
          "workspaceEpoch": 1,
          "snapshotId": "22222222-2222-2222-2222-222222222222",
          "transactionRevision": 1
        },
        "workspace": {
          "alias": "sample"
        }
      }
    }
  ]
}