guildhouse-proto/bascule/v1/ceremony.proto

syntax = "proto3";
package bascule.v1;

import "google/protobuf/timestamp.proto";

// Governance Ceremony Service — multi-stakeholder approval flows
// triggered by Accord policy when a mutation requires human sign-off.
service CeremonyService {
    // Create a new governance ceremony.
    rpc CreateCeremony (CreateCeremonyRequest) returns (CreateCeremonyResponse);

    // Record an approval or denial on a pending ceremony.
    rpc ApproveCeremony (ApproveCeremonyRequest) returns (ApproveCeremonyResponse);

    // Deny a pending ceremony.
    rpc DenyCeremony (DenyCeremonyRequest) returns (DenyCeremonyResponse);

    // Cancel a pending ceremony (requestor or admin).
    rpc CancelCeremony (CancelCeremonyRequest) returns (CancelCeremonyResponse);

    // Get the current status of a ceremony.
    rpc GetCeremony (GetCeremonyRequest) returns (GetCeremonyResponse);

    // List pending ceremonies, optionally filtered.
    rpc ListPendingCeremonies (ListPendingCeremoniesRequest) returns (ListPendingCeremoniesResponse);

    // Get the resolution proof for a completed ceremony.
    rpc GetCeremonyProof (GetCeremonyProofRequest) returns (GetCeremonyProofResponse);
}

// --- Create ---

message CreateCeremonyRequest {
    string ceremony_type = 1;  // "single_approval", "quorum_approval", etc.
    CeremonySubjectMsg subject = 2;
    uint32 required_approvals = 3;
    repeated string approver_roles = 4;
    uint32 ttl_hours = 5;       // 0 = default (24h)
    string intent_id = 6;       // optional linked MutationIntent
    string run_id = 7;          // optional linked pipeline run
    uint64 pr_number = 8;       // optional linked PR
    string remote_name = 9;     // optional remote name
}

message CreateCeremonyResponse {
    string ceremony_id = 1;
    string status = 2;          // "pending" or "approved" (for self-grant)
    google.protobuf.Timestamp expires_at = 3;
    string error = 4;
}

// --- Approve ---

message ApproveCeremonyRequest {
    string ceremony_id = 1;
    string approver_identity = 2;
    string approver_role = 3;
    string comment = 4;
}

message ApproveCeremonyResponse {
    bool success = 1;
    string status = 2;          // updated status after approval
    string error = 3;
}

// --- Deny ---

message DenyCeremonyRequest {
    string ceremony_id = 1;
    string approver_identity = 2;
    string approver_role = 3;
    string comment = 4;
}

message DenyCeremonyResponse {
    bool success = 1;
    string status = 2;
    string error = 3;
}

// --- Cancel ---

message CancelCeremonyRequest {
    string ceremony_id = 1;
}

message CancelCeremonyResponse {
    bool success = 1;
    string error = 2;
}

// --- Get ---

message GetCeremonyRequest {
    string ceremony_id = 1;
}

message GetCeremonyResponse {
    string ceremony_id = 1;
    string ceremony_type = 2;
    CeremonySubjectMsg subject = 3;
    string status = 4;
    uint32 required_approvals = 5;
    uint32 current_approvals = 6;
    repeated CeremonyApprovalMsg approvals = 7;
    google.protobuf.Timestamp created_at = 8;
    google.protobuf.Timestamp expires_at = 9;
    string intent_id = 10;
    string run_id = 11;
    uint64 pr_number = 12;
    string remote_name = 13;
    string error = 14;
}

// --- List Pending ---

message ListPendingCeremoniesRequest {
    string intent_id = 1;       // optional filter
}

message ListPendingCeremoniesResponse {
    repeated GetCeremonyResponse ceremonies = 1;
}

// --- Proof ---

message GetCeremonyProofRequest {
    string ceremony_id = 1;
}

message GetCeremonyProofResponse {
    string ceremony_id = 1;
    string status = 2;
    string proof_hash = 3;
    repeated CeremonyApprovalMsg approvals = 4;
    google.protobuf.Timestamp resolved_at = 5;
    string error = 6;
}

// --- Shared messages ---

message CeremonySubjectMsg {
    string subject_type = 1;    // "mutation_intent", "pipeline_merge", "schematic_publish", "custom"
    string reference_id = 2;    // intent_id, run_id, "name:version", or custom ref
    string description = 3;     // human-readable label
    map<string, string> metadata = 4;  // extra fields
}

message CeremonyApprovalMsg {
    string approver_identity = 1;
    string approver_role = 2;
    string decision = 3;        // "approve" or "deny"
    string comment = 4;
    google.protobuf.Timestamp decided_at = 5;
}