Specification v0.1.0-draft

Error Model

All error codes, conditions, and recovery guidance.

Error Response Format

Every error response from the Field uses this structure:

{
  "code": "<ErrorCode>",
  "message": "<string>",
  "operation": "<OperationType>",
  "recoverable": "<boolean>",
  "suggested_action": "<string | null>"
}

Field	Description
`code`	Machine-readable error code.
`message`	Human-readable description of what went wrong.
`operation`	The operation that triggered the error.
`recoverable`	Whether the caller can retry or correct and re-submit.
`suggested_action`	Optional guidance on how to recover.

Validation Errors

Errors caused by invalid or missing fields in the request payload.

Code	Description	Recoverable
`MISSING_INTENT`	RECORD submitted without `intent.purpose`	Yes — resubmit with intent
`MISSING_CONFIDENCE`	Committed RECORD at Level 1+ without `confidence.score` or `confidence.reasoning`	Yes — resubmit with confidence
`INVALID_CONFIDENCE`	`confidence.score` is outside the 0.0–1.0 range	Yes — correct and resubmit
`INVALID_TYPE`	Unknown or unsupported `MemoryType` value	Yes — use a supported type
`AGENT_NOT_REGISTERED`	Operation submitted by an agent that hasn't called REGISTER	Yes — call REGISTER first
`AGENT_ID_TAKEN`	REGISTER requested with an `id` already in use	Yes — choose a different ID
`CONFLICT_NOT_FOUND`	MERGE references a conflict that doesn't exist	No
`UNIT_NOT_FOUND`	DETECT or REPLAY references a unit that doesn't exist	No
`INVALID_TRANSITION`	A state machine transition was attempted from an invalid current state	Yes — check current state first
`UNSUPPORTED_OPERATION`	The operation is not supported at this Field's conformance level	No

Operational Errors

Errors caused by infrastructure or processing failures after a valid request was received.

Code	Description	Recoverable
`ENRICHMENT_FAILED`	Embedding generation or enrichment failed; unit committed as `pending_enrichment`	Yes — unit is still committed; enrichment will retry
`DETECTION_TIMEOUT`	Conflict detection timed out; unit committed but detection deferred	Yes — call DETECT manually
`MERGE_FAILED`	Conflict resolution failed (e.g., vote did not reach quorum)	Yes — retry with a different strategy
`REPLAY_TOO_LARGE`	Reasoning chain is too large to reconstruct in a single response	Yes — use `summary` or `detailed` depth
`STORAGE_FULL`	Persistence store is at capacity	No — run COMPACT or expand storage capacity

System Errors

Errors caused by unrecoverable system conditions.

Code	Description	Recoverable
`EPOCH_OVERFLOW`	The logical clock has overflowed its integer range	No — requires system restart with a checkpoint
`INTERNAL_ERROR`	An unexpected internal failure occurred	No

Partial Failure Semantics

Some operations may partially succeed. The Field uses specific conventions to communicate this:

RECORD with enrichment failure:

{
  "status": "accepted",
  "memory_unit_id": "mem-abc",
  "epoch": 5,
  "conflicts_detected": [],
  "warnings": [{ "code": "ENRICHMENT_FAILED", "message": "Embedding generation failed. Unit committed as pending_enrichment." }]
}

RECORD with conflict detection timeout:

{
  "status": "accepted",
  "memory_unit_id": "mem-abc",
  "epoch": 5,
  "conflicts_detected": [],
  "conflict_detection": "deferred"
}

In both cases the memory unit is committed — the partial failure only affects enrichment or detection, not persistence.

COMPACT

Archive, summarize, or purge aged memory units.

Conformance Levels

Complete requirements for Level 0 through Level 3.