orgdraft API

Table of Contents

• upsquad/orgdraft/v1/draft.proto

  • AddOpRequest

  • AddOpResponse

  • CreateDraftRequest

  • CreateDraftResponse

  • DiscardRequest

  • DiscardResponse

  • Draft

  • DraftOp

  • GetDraftRequest

  • GetDraftResponse

  • ListDraftsRequest

  • ListDraftsResponse

  • ListOpsRequest

  • ListOpsResponse

  • OpVerdict

  • PublishRequest

  • PublishResponse

  • RemoveOpRequest

  • RemoveOpResponse

  • ValidateRequest

  • ValidateResponse

  • DraftFilter

  • DraftStatus

  • OpType

  • OpVerdictStatus

  • PublishOutcome

  • OrgDraftService

• Scalar Value Types

Top

upsquad/orgdraft/v1/draft.proto

AddOpRequest

AddOpRequest appends one op to a draft.

Field	Type	Label	Description
draft_id	string		The draft to append to (UUID).
op_type	OpType		The operation kind.
target_member_id	string		The member the op acts on (UUID); empty for create.
payload	google.protobuf.Struct		Op-specific arguments (see HLD-B §5.2).

AddOpResponse

AddOpResponse carries the appended op with its assigned seq.

Field	Type	Label	Description
op	DraftOp		The appended op.

CreateDraftRequest

CreateDraftRequest opens a draft. The org is taken from the caller's scope.

Field	Type	Label	Description
title	string		Working-draft label (optional).

CreateDraftResponse

CreateDraftResponse carries the new draft.

Field	Type	Label	Description
draft	Draft		The created draft.

DiscardRequest

DiscardRequest discards a draft.

Field	Type	Label	Description
draft_id	string		The draft to discard (UUID).

DiscardResponse

DiscardResponse confirms discard.

Field	Type	Label	Description
discarded	bool		True when the draft transitioned to discarded.

Draft

Draft is one org_drafts header row.

Field	Type	Label	Description
id	string		Draft id (UUID).
org_id	string		The owning organisation (UUID).
title	string		Working-draft label (may be empty).
created_by	string		The author member id (UUID).
status	DraftStatus		Lifecycle state.
base_version_id	string		The version this draft was opened against (UUID); empty when the org had no version history at creation.
approval_id	string		The governance approval opened on Publish (UUID); empty until then.
published_version_id	string		The org_versions row produced on successful publish (UUID); empty until published.
created_at	google.protobuf.Timestamp		When the draft was created.
updated_at	google.protobuf.Timestamp		When the draft was last modified.

DraftOp

DraftOp is one org_draft_ops row.

Field	Type	Label	Description
id	string		Op id (UUID).
draft_id	string		The owning draft (UUID).
seq	int32		1-based apply order within the draft.
op_type	OpType		The operation kind.
target_member_id	string		The member the op acts on (UUID); empty for create.
payload	google.protobuf.Struct		Op-specific arguments (see HLD-B §5.2).
last_validation	OpVerdict		The most recent per-op verdict from Validate (null until first validated).
conflict	bool		Whether this op is currently flagged as a base-version conflict.

GetDraftRequest

GetDraftRequest deep-links a draft.

Field	Type	Label	Description
draft_id	string		The draft to fetch (UUID).

GetDraftResponse

GetDraftResponse carries the header plus its ops.

Field	Type	Label	Description
draft	Draft		The draft header.
ops	DraftOp	repeated	The draft's ops, ordered by seq ascending.

ListDraftsRequest

ListDraftsRequest pages the org's drafts.

Field	Type	Label	Description
filter	DraftFilter		Which slice to return.
page_size	int32		Max drafts to return (1..100; default 50).
page_token	int64		Keyset cursor (updated_at micros of the last row); zero starts at newest.

ListDraftsResponse

ListDraftsResponse carries one page of drafts, newest first.

Field	Type	Label	Description
drafts	Draft	repeated	The page of drafts.
next_page_token	int64		Cursor for the next page; zero when exhausted.

ListOpsRequest

ListOpsRequest lists a draft's ops.

Field	Type	Label	Description
draft_id	string		The draft to list (UUID).

ListOpsResponse

ListOpsResponse carries the ops in apply order.

Field	Type	Label	Description
ops	DraftOp	repeated	The ops, ordered by seq ascending.

OpVerdict

OpVerdict is the per-op result captured at Validate.

Field	Type	Label	Description
seq	int32		The op's seq this verdict belongs to.
op_id	string		The op id (UUID) this verdict belongs to.
status	OpVerdictStatus		Validity outcome.
field	string		The offending payload field, when status is INVALID (e.g. "reports_to").
message	string		Human-readable explanation of an INVALID / CONFLICT verdict.

PublishRequest

PublishRequest publishes (or resumes publishing) a draft.

Field	Type	Label	Description
draft_id	string		The draft to publish (UUID).

PublishResponse

PublishResponse carries the publish outcome.

Field	Type	Label	Description
outcome	PublishOutcome		High-level outcome.
version_id	string		The published org_versions row (UUID); set when outcome is PUBLISHED.
approval_id	string		The governance approval (UUID); set for both gated and auto-approved publishes.
status	DraftStatus		The draft's resulting status.
verdicts	OpVerdict	repeated	Populated when outcome is REJECTED: the failing verdicts.
created_member_ids	string	repeated	created_member_ids carries the UUIDs of members created by create ops in this publish, in op-sequence order. Populated when outcome is PUBLISHED so the frontend can act on a freshly added person (e.g. open their detail panel) without re-deriving the id from the tree. Empty when the publish created no members.

RemoveOpRequest

RemoveOpRequest deletes one op from a draft.

Field	Type	Label	Description
draft_id	string		The owning draft (UUID).
op_id	string		The op to remove (UUID).

RemoveOpResponse

RemoveOpResponse confirms removal.

Field	Type	Label	Description
removed	bool		True when the op existed and was removed.

ValidateRequest

ValidateRequest validates a draft.

Field	Type	Label	Description
draft_id	string		The draft to validate (UUID).

ValidateResponse

ValidateResponse is the per-op validation report.

Field	Type	Label	Description
verdicts	OpVerdict	repeated	Per-op verdicts, ordered by seq.
publishable	bool		True iff every op is VALID and no op is CONFLICT (publishable).

DraftFilter

DraftFilter selects which drafts ListDrafts returns.

Name	Number	Description
DRAFT_FILTER_UNSPECIFIED	0	Default: open (non-terminal) drafts.
DRAFT_FILTER_OPEN	1	Only open drafts (draft / validating / pending_approval).
DRAFT_FILTER_MINE	2	Only the caller's own drafts.
DRAFT_FILTER_ALL	3	All drafts including published / discarded.

DraftStatus

DraftStatus is the draft lifecycle state.

Name	Number	Description
DRAFT_STATUS_UNSPECIFIED	0	Unset / unknown status.
DRAFT_STATUS_DRAFT	1	Editable; accepting ops.
DRAFT_STATUS_VALIDATING	2	A validation replay is in progress.
DRAFT_STATUS_PENDING_APPROVAL	3	Publish opened an approval and is holding the apply (two-phase gate).
DRAFT_STATUS_PUBLISHED	4	Applied; produced a published_version_id.
DRAFT_STATUS_DISCARDED	5	Abandoned; retained for audit, no longer editable.

OpType

OpType is the member-level operation kind (HLD-B §5.2). Unit-level ops (merge / split) are out of FW1 scope.

Name	Number	Description
OP_TYPE_UNSPECIFIED	0	Unset / unknown op type.
OP_TYPE_CREATE	1	Create a new member (target_member_id empty).
OP_TYPE_UPDATE	2	Update mutable fields of an existing member.
OP_TYPE_MOVE	3	Reparent a member (change reports_to).
OP_TYPE_REMOVE	4	Soft-delete a member, reparenting reports to a successor.
OP_TYPE_PROMOTE	5	Promote a member, optionally replacing another.

OpVerdictStatus

OpVerdictStatus is the validity outcome of one op at the last Validate.

Name	Number	Description
OP_VERDICT_STATUS_UNSPECIFIED	0	Not yet validated.
OP_VERDICT_STATUS_VALID	1	The op replayed cleanly against the cumulative working copy.
OP_VERDICT_STATUS_INVALID	2	The op failed a validator (cycle / clearance / email / missing target).
OP_VERDICT_STATUS_CONFLICT	3	The op's referenced member diverged from the draft's base version (Design Call 1, fail-closed). Publish aborts while any op is CONFLICT.

PublishOutcome

PublishOutcome is the high-level result of a Publish call.

Name	Number	Description
PUBLISH_OUTCOME_UNSPECIFIED	0	Unset / unknown outcome.
PUBLISH_OUTCOME_PUBLISHED	1	The draft applied and produced a version.
PUBLISH_OUTCOME_PENDING_APPROVAL	2	The draft is sensitive; an approval was opened and the apply is deferred.
PUBLISH_OUTCOME_REJECTED	3	Validation / conflict check failed; nothing was written.

OrgDraftService

OrgDraftService is the external (Connect / gRPC) surface for the org restructure draft workflow. All operations are tenant-scoped via the gateway-derived scope and PostgreSQL row-level security.

Method Name	Request Type	Response Type	Description
CreateDraft	CreateDraftRequest	CreateDraftResponse	CreateDraft opens an empty draft anchored to the org's latest version (the optimistic-concurrency base for conflict detection).
AddOp	AddOpRequest	AddOpResponse	AddOp appends one member-level op to a draft, assigning the next seq.
RemoveOp	RemoveOpRequest	RemoveOpResponse	RemoveOp deletes one op from a draft and re-sequences the tail.
ListOps	ListOpsRequest	ListOpsResponse	ListOps returns a draft's ops in apply order with their last verdicts.
GetDraft	GetDraftRequest	GetDraftResponse	GetDraft returns a draft header plus its ops (deep-link into an in-progress draft).
Validate	ValidateRequest	ValidateResponse	Validate replays the ops into a doomed sub-transaction and returns per-op verdicts (valid / invalid / conflict). It never commits any mutation.
Publish	PublishRequest	PublishResponse	Publish applies a validated draft. Two-phase (Design Call 2): sensitive drafts defer the apply until an ApprovalService grant; non-sensitive drafts apply immediately. Re-invoking Publish on a pending_approval draft resumes and applies once the approval is granted.
Discard	DiscardRequest	DiscardResponse	Discard marks a draft discarded; its ops are retained for audit but the draft can no longer be edited or published.
ListDrafts	ListDraftsRequest	ListDraftsResponse	ListDrafts lists the org's drafts filtered by open / mine / all.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)