Governance annotations

When to use this pageCopy Anchor Link

You need it when you write or review a port or plugin: to see what an RPC must declare, to understand why the host treats a call as it does, or to look up the exact option names. Policy authors use the same vocabulary: RISK_CLASS_* values appear in autonomy policies.

MechanismCopy Anchor Link

Annotations are protobuf extensions. The Engine and the plugin host read them from descriptors (through protobuf reflection) before policy evaluation; they are never parsed from .proto text. Two extensions carry the contract:

extend google.protobuf.MethodOptions {
  ActionOptions action = 50001;
}

extend google.protobuf.FieldOptions {
  FieldAnnotations field = 50002;
}

Extension number 50003 is numinance.kinds.v1.merge on FieldOptions (see Kinds and JSON Schema). Every RPC in every Numinance service sets the action option, and every message and field in the file is since: "1.0.0".

Because the host reads annotations from its own copy of the descriptors, a plugin cannot change the risk or execution mode of a verb by shipping a different file. A shared port file that differs from the host copy in any option fails install (GetDescriptors).

RiskClassCopy Anchor Link

RiskClass classifies the worst-case effect of an action. A change's risk class is the maximum over its playbook steps. A capability's risk_floor can never be lowered, neither by a provider nor by a customer; lowering the risk of an existing RPC in a later release is a contract-breaking change.

ExecModeCopy Anchor Link

ExecMode says how an action is executed and which verb shape it follows.

ActionOptionsCopy Anchor Link

ActionOptions is the governance contract of one RPC. The host checks each invocation against these values and the caller's grant before dispatch.

message ActionOptions {
  RiskClass risk = 1;
  ExecMode exec = 2;
  bool idempotent = 3;
  bool supports_dry_run = 4;
  string compensating_action = 5;
  repeated string evidence = 6;
  string capability = 7;
  string since = 8;
  string llm_description = 9;
  repeated string tool_groups = 10;
  repeated string scopes = 11;
}

FieldAnnotationsCopy Anchor Link

FieldAnnotations carries lifecycle and sensitivity metadata for one field and is set through the field option.

message FieldAnnotations {
  string since = 1;
  string deprecated_in = 2;
  string replaced_by = 3;
  bool sensitive = 4;
  bool host_only = 5;
  bool resource_name = 6;
}

Two rules of resource_name matter for port authors. A request that names no resource through a marked field is denied, and so is a request with an unknown field, so never mark an optional filter field: mark only the fields a call must name. An empty marked string names nothing and is never defaulted to an implicit resource.

Annotated RPCs, exactly as they appearCopy Anchor Link

These excerpts are copied from the port files.

A read that needs a scope and a capabilityCopy Anchor Link

  rpc Lookup(LookupRequest) returns (LookupResponse) {
    option (numinance.annotations.v1.action) = {
      risk: RISK_CLASS_READ
      exec: EXEC_MODE_SYNC
      idempotent: true
      supports_dry_run: false
      capability: "transparencylog.lookup"
      since: "1.0.0"
      llm_description: "Finds the index of a leaf in the transparency log."
      scopes: "evidence.read"
    };
  }

Lookup is gated by a non-Core capability, so a log without a search index does not serve it. The caller needs the evidence.read scope.

A write with declared evidence and a compensating actionCopy Anchor Link

  rpc OpenPullRequest(OpenPullRequestRequest) returns (OpenPullRequestResponse) {
    option (numinance.annotations.v1.action) = {
      risk: RISK_CLASS_MEDIUM
      exec: EXEC_MODE_SYNC
      idempotent: true
      supports_dry_run: true
      compensating_action: "ScmService.UpdatePullRequest"
      evidence: "pr-ref"
      since: "1.0.0"
      llm_description: "Opens a pull request for a verified candidate branch."
    };
  }

If the plugin succeeds but the pr-ref evidence is missing, the host records PARTIAL, not success. A compensating action exists (UpdatePullRequest, which can close the pull request).

A privileged actionCopy Anchor Link

  rpc MergePullRequest(MergePullRequestRequest) returns (MergePullRequestResponse) {
    option (numinance.annotations.v1.action) = {
      risk: RISK_CLASS_PRIVILEGED
      exec: EXEC_MODE_SYNC
      idempotent: true
      supports_dry_run: true
      compensating_action: "ScmService.CommentOnPullRequest"
      since: "1.0.0"
      llm_description: "Merges a verified pull request into its base branch."
    };
  }

The annotation sets the floor for risk. Who may call it is a separate rule: per the port's comment, merging is allowed only to the release-pipeline identity under a grant of level Merge or above, and the policy floors refuse the author of the Change. See Capability ports.

A long-running operationCopy Anchor Link

  rpc StartOperation(StartOperationRequest) returns (StartOperationResponse) {
    option (numinance.annotations.v1.action) = {
      risk: RISK_CLASS_HIGH
      exec: EXEC_MODE_OPERATION
      idempotent: true
      supports_dry_run: true
      compensating_action: "CiExecutorService.CancelOperation"
      evidence: "ci-run-ref"
      since: "1.0.0"
      llm_description: "Starts one run of a customer pipeline at a given commit."
    };
  }

Field annotationsCopy Anchor Link

  string repository = 1 [(numinance.annotations.v1.field) = {since: "1.0.0", resource_name: true}];

  numinance.types.v1.Reference worktree_ref = 6 [(numinance.annotations.v1.field) = {
    since: "1.0.0"
    host_only: true
  }];

  string handle = 1 [(numinance.annotations.v1.field) = {
    since: "1.0.0"
    sensitive: true
  }];

Versioning rules the annotations enforceCopy Anchor Link

• A capability's risk_floor can never be lowered, neither by a provider nor by a customer. Lowering the risk of an existing RPC in a later release is a contract-breaking change.
• Every addition after 1.0.0 carries since. See Protocol overview.
• *_UNSPECIFIED values are rejected by lint and by the plugin host.

Failure modes and safeguardsCopy Anchor Link

Next stepsCopy Anchor Link