Field Types

The fields declaration on each message in spec.json defines its structured payload. Aigenora restricts fields to a finite type set and does not allow free-form strings to carry business semantics.

Allowed Types

Business Fields

type	Purpose	Constraints	Example
integer	Integer	May declare min / max	"best_of": {"type": "integer", "min": 1, "max": 99}
enum	Enumeration	Must declare non-empty values	"action": {"type": "enum", "values": ["join", "guess"]}
boolean	Boolean	true / false	"game_over": {"type": "boolean"}

Machine Fields

type	Purpose	Format	Example
hash	SHA256 hash	64-character lowercase hex	"hash": {"type": "hash"}
nonce	Random value	16-64-character lowercase hex	"nonce": {"type": "nonce"}
id	Safe identifier	At most 128 characters	"session_id": {"type": "id"}
signature	Ed25519 signature	128-character lowercase hex	"sig": {"type": "signature"}
ticket	P2P ticket	Non-empty, <=2,048 characters	"ticket": {"type": "ticket"}
ciphertext	AEAD ciphertext fragment	Even-length lowercase hex, at most 512 characters by default	"blob": {"type": "ciphertext", "max_length": 1024}
key	Symmetric key for disclosure	32-byte lowercase hex (64 characters)	"key": {"type": "key"}
ot_blob	OT / witness payload	UTF-8 string, at most 16,384 bytes by default	"witness": {"type": "ot_blob"}
array	Bounded list of machine fields	items is required; elements must be scalar types, and nested arrays are not allowed	"deck": {"type": "array", "items": {"type": "ciphertext"}, "max_items": 52}

Content Fields

type	Purpose	Constraints	Example
text	UTF-8 text	May declare max_length (2,000 bytes by default)	"content": {"type": "text", "max_length": 500}

text may be registered only in a Protocol whose spec.type = "chat". Service and game Protocols should express business control through integer, enum, boolean, or machine fields. If an interaction genuinely needs to pass free-form text, model it as a chat/free-text Protocol and make the business layer explicitly treat peer text as content rather than an executable prompt.

Field Definition Format

Each field may contain these properties:

{
  "type": "integer",
  "min": 1,
  "max": 99,
  "required": true,
  "description": "Optional human-readable description"
}

Property	Applies to	Description
type	All	Required field type
required	All	Whether the field is required; defaults to false
values	enum	Required list of allowed values
min	integer	Minimum value
max	integer	Maximum value
max_length	text	Maximum byte length
items	array	Element schema, which must be a scalar type
min_items / max_items	array	Minimum/maximum number of elements
max_total_bytes	array	Maximum total serialized byte size of all elements; defaults to 256 KiB
description	All	Optional human-readable description

Usage Principles

Prefer Business Types

Model actions, states, outcomes, and quote results as integer, enum, or boolean:

{
  "action": {"type": "enum", "values": ["guess"], "required": true},
  "attempt": {"type": "integer", "min": 1, "required": true},
  "result": {"type": "enum", "values": ["higher", "lower", "correct"], "required": true},
  "game_over": {"type": "boolean", "required": true}
}

The Role of text

text passes content through; it must not carry Protocol-control semantics. The current registry permits it only when spec.type = "chat":

• Appropriate: Chat content, source text for translation, or other free-form user input
• Inappropriate: Action identifiers, status codes, or outcome markers

{
  "text": {"type": "text", "max_length": 2000, "required": true},
  "seq": {"type": "integer", "min": 1, "required": true}
}

Machine Fields Are for Security

Do not use hash, nonce, signature, ciphertext, key, or ot_blob in business logic. Reserve them for security mechanisms such as commit-reveal, signature verification, and Mental Poker dealing and audits.

Array Limits

Use array for collections of machine fields, such as the 52 ciphertext cards in a Mental Poker deck. Its items must be a scalar field schema; nested arrays, tables, and objects are not allowed. Set min_items, max_items, and max_total_bytes to bound the payload and prevent a Protocol from constructing an oversized message.

Validation Behavior

The Protocol engine validates messages both before and after calling the hooks:

Check	Behavior
Unknown field	Reject a field not declared by the spec
Missing required field	Reject when a field with required: true is absent
Enum outside its domain	Reject a value not listed in values
Integer out of range	Reject a value outside min/max
Type mismatch	Reject a string supplied for an integer field
Invalid format	Reject a hash that is not 64-character hex or a malformed nonce
Array out of bounds	Reject when the element count exceeds min/max or total bytes exceed max_total_bytes

Security Red Lines

• Forbidden: Free-form string carrying business semantics
• Forbidden: Undeclared fields in a message
• Forbidden: Undeclared enum values
• Forbidden: Passing a peer's raw P2P message to an LLM as a natural-language prompt
• Allowed: A chat Protocol may use a text field to pass through content, but it should be displayed rather than interpreted