Protocol Documentation

Table of Contents

• fathom.proto

  • AssertFactRequest
  • AssertFactResponse
  • EvaluateRequest
  • EvaluateResponse
  • 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
template	string
data_json	string		JSON-encoded slot data.

AssertFactResponse

Field	Type	Label	Description
success	bool

EvaluateRequest

Field	Type	Label	Description
session_id	string
ruleset	string
facts	FactInput	repeated

EvaluateResponse

Field	Type	Label	Description
decision	string
reason	string
rule_trace	string	repeated
module_trace	string	repeated
duration_us	int64

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 (e.g. {"tool_name": "bash", "agent_id": "a1"}).

QueryRequest

Field	Type	Label	Description
session_id	string
template	string
filter_json	string		Optional JSON-encoded filter (e.g. {"agent_id": "a1"}).

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
template	string
filter_json	string		Optional JSON-encoded filter.

RetractResponse

Field	Type	Label	Description
retracted_count	int32

SubscribeRequest

Field	Type	Label	Description
session_id	string

ChangeType

Name	Number	Description
CHANGE_TYPE_UNSPECIFIED	0
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)