Protocol Documentation

Table of Contents

• fathom.proto

  • AssertFactRequest
  • AssertFactResponse
  • EvaluateRequest
  • EvaluateResponse
  • EvaluateResponse.MetadataEntry
  • FactChange
  • FactInput
  • QueryRequest
  • QueryResponse
  • ReloadRequest
  • ReloadResponse
  • RetractRequest
  • RetractResponse

  • SubscribeRequest

  • ChangeType

  • FathomService

• Scalar Value Types

Top

fathom.proto

AssertFactRequest

Field	Type	Label	Description
session_id	string		Required. Working memory is per session; create the session with Evaluate first; an unknown one is NOT_FOUND. An empty session_id is refused with INVALID_ARGUMENT.
template	string
data_json	string		JSON-encoded slot data, a JSON object; anything else is INVALID_ARGUMENT.

AssertFactResponse

Field	Type	Label	Description
success	bool

EvaluateRequest

Field	Type	Label	Description
session_id	string		Optional. Empty: a stateless evaluation against the server's engine. Set: the session's working memory is used, and Evaluate is the call that opens it -- an unknown id is created, bound to ruleset (empty if none is named). A known id is joined; naming a different ruleset than the session was opened with is FAILED_PRECONDITION. A server that mounts an engine refuses sessions with FAILED_PRECONDITION.
ruleset	string		Ruleset path relative to FATHOM_RULESET_ROOT.
facts	FactInput	repeated

EvaluateResponse

Field	Type	Label	Description
decision	string	optional	Optional so that "no rule produced a decision" is distinguishable from a rule that decided the empty string. proto3 has no other way to say it: an unset non-optional string arrives as "" at every client.
reason	string	optional
rule_trace	string	repeated
module_trace	string	repeated
duration_us	int64
metadata	EvaluateResponse.MetadataEntry	repeated	The then.metadata of the rule that wrote the decision. Carried here so a gRPC caller sees the same result shape a REST caller does; control ids and other rule-authored context live in it.
attestation_token	string	optional	Ed25519 JWT over this evaluation, present only when the server was built with an attestation service.

EvaluateResponse.MetadataEntry

Field	Type	Label	Description
key	string
value	string

FactChange

Field	Type	Label	Description
change_type	ChangeType
template	string
data_json	string		JSON-encoded slot data of the changed fact.

FactInput

Field	Type	Label	Description
template	string
data_json	string		JSON-encoded slot data, a JSON object (e.g. {"tool_name": "bash", "agent_id": "a1"}). Anything else is INVALID_ARGUMENT.

QueryRequest

Field	Type	Label	Description
session_id	string		Required. Working memory is per session; create the session with Evaluate first; an unknown one is NOT_FOUND. An empty session_id is refused with INVALID_ARGUMENT.
template	string
filter_json	string		Optional JSON-object filter (e.g. {"agent_id": "a1"}). Empty matches every fact of the template; any non-object JSON, null included, is INVALID_ARGUMENT.

QueryResponse

Field	Type	Label	Description
facts_json	string	repeated	Each entry is a JSON-encoded dict representing one fact.

ReloadRequest

Field	Type	Label	Description
ruleset_path	string
ruleset_yaml	string
signature	bytes

ReloadResponse

Field	Type	Label	Description
ruleset_hash_before	string
ruleset_hash_after	string
attestation_token	string

RetractRequest

Field	Type	Label	Description
session_id	string		Required. Working memory is per session; create the session with Evaluate first; an unknown one is NOT_FOUND. An empty session_id is refused with INVALID_ARGUMENT.
template	string
filter_json	string		Optional JSON-object filter. Empty retracts every fact of the template; any non-object JSON, null included, is INVALID_ARGUMENT.

RetractResponse

Field	Type	Label	Description
retracted_count	int32

SubscribeRequest

Field	Type	Label	Description
session_id	string		Required. Working memory is per session; create the session with Evaluate first; an unknown one is NOT_FOUND. An empty session_id is refused with INVALID_ARGUMENT.

ChangeType

Name	Number	Description
CHANGE_TYPE_UNSPECIFIED	0
CHANGE_TYPE_ASSERT	1
CHANGE_TYPE_RETRACT	2
ASSERT	1
RETRACT	2

FathomService

Method Name	Request Type	Response Type	Description
Evaluate	EvaluateRequest	EvaluateResponse	Evaluate asserted facts against loaded rules and return a decision.
AssertFact	AssertFactRequest	AssertFactResponse	Assert one or more facts into working memory.
Query	QueryRequest	QueryResponse	Query working memory for facts matching a template and optional filter.
Retract	RetractRequest	RetractResponse	Retract facts matching a template and optional filter.
SubscribeChanges	SubscribeRequest	FactChange stream	Stream working-memory changes as they occur during evaluation.
Reload	ReloadRequest	ReloadResponse	Hot-reload the ruleset from a path or inline YAML.

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)