Entity Relationship Model

HatiData V2 introduces a strict entity language for agent lifecycle management. Every entity has a defined role, relationships, and integrity constraints. This page is the visual map.

The Entity Hierarchy

Project
 │
 ├── Task (intent: what needs to be done)
 │    │
 │    └── TaskAttempt (execution: a single run)
 │         │
 │         ├── ModelDecision (routing: which model and why)
 │         │    └── LlmInvocation (call: the actual API request)
 │         │
 │         ├── ArtifactInstance (output: what was produced)
 │         │    └── ArtifactValidation (verification: schema + contract check)
 │         │
 │         ├── RecoveryAction (repair: what happened after failure)
 │         │
 │         └── WorkflowEvent (audit: immutable state transition log)
 │
 ├── AgentMemory (persistent: cross-task knowledge)
 │    └── ReasoningStep (CoT: hash-chained thought ledger)
 │
 ├── Branch (isolation: copy-on-write data fork)
 │
 └── GateEvaluation (governance: human-in-the-loop checkpoint)
      └── ReleaseDecision (ship/block: aggregated evidence verdict)

Entity Definitions

Intent vs Execution

Entity	Role	Mutability	Cardinality
Task	"Generate the architecture"	Immutable after creation	1 per dispatch
TaskAttempt	"Attempt #2 using DeepSeek V3"	State transitions only	Many per Task

A Task captures what needs to happen. An Attempt captures how it happened. This separation is the foundation of V2 — it enables retry comparison, cost attribution, and recovery lineage.

Causality Chain

Entity	Role	Links To
ModelDecision	"Selected DeepSeek V3 via vertex_ai policy"	TaskAttempt
LlmInvocation	"Called deepseek-ai/deepseek-v3.2-maas, 4200 input tokens, $0.003"	ModelDecision
ArtifactInstance	"Produced api_contract with content_hash sha256:abc"	TaskAttempt
ArtifactValidation	"Schema validator passed, contract constraints satisfied"	ArtifactInstance

Every artifact has a causality chain: you can trace any output back through its invocation, model decision, attempt, and task to the original intent.

Governance Entities

Entity	Role	Links To
GateEvaluation	"G2 Architecture Review: 3 predicates passed, 1 requires human"	Project phase
ReleaseDecision	"Ship — all evidence bundles present, confidence > 0.9"	GateEvaluation
RecoveryAction	"L2 escalation: switched from Haiku to Sonnet after schema failure"	TaskAttempt

Memory Entities

Entity	Role	Links To
AgentMemory	"proj:abc:requirements — stored by IntakeAnalyst"	Project, Branch
ReasoningStep	"Step 3: decided to use Axum framework because..."	Project, Agent

Integrity Constraints

HatiData V2 enforces these invariants at the database level:

No Orphan Artifacts

Every artifact must have a valid parent chain:

ArtifactInstance.attempt_id → TaskAttempt.id → Task.id → Project.id

If any link is broken, the artifact is considered orphaned and cannot be consumed by downstream agents.

One Active Attempt Per Task

CREATE UNIQUE INDEX idx_one_active_attempt
ON hd_runtime.task_attempts (task_id)
WHERE status NOT IN ('completed_verified', 'terminal_failed');

This prevents two agents from working on the same task simultaneously.

Append-Only Events

REVOKE UPDATE, DELETE ON hd_runtime.workflow_events FROM ALL;

Workflow events form a tamper-proof audit trail. Once written, they cannot be modified or deleted.

Lease Exclusivity

-- Atomic claim: only one agent can hold a lease
SELECT id FROM hd_runtime.task_attempts
WHERE status = 'queued' AND task_id = :task_id
FOR UPDATE SKIP LOCKED
LIMIT 1;

Relationship Diagram

┌─────────┐     1:N     ┌──────────────┐     1:N     ┌────────────────┐
│ Project │─────────────▶│     Task     │─────────────▶│  TaskAttempt   │
└─────────┘              └──────────────┘              └───────┬────────┘
                                                               │
                              ┌─────────────────┬──────────────┼──────────────┐
                              │                 │              │              │
                              ▼                 ▼              ▼              ▼
                       ┌──────────────┐  ┌─────────────┐  ┌──────────┐  ┌─────────┐
                       │ModelDecision │  │  Artifact   │  │ Recovery │  │Workflow │
                       │              │  │  Instance   │  │  Action  │  │  Event  │
                       └──────┬───────┘  └──────┬──────┘  └──────────┘  └─────────┘
                              │                 │
                              ▼                 ▼
                       ┌──────────────┐  ┌─────────────┐
                       │LlmInvocation│  │  Artifact   │
                       │              │  │ Validation  │
                       └──────────────┘  └─────────────┘

V1 vs V2 Entity Comparison

V1 Entity	V2 Replacement	What Changed
agent_task_logs	Task + TaskAttempt	Split intent from execution
agent_states	WorkflowEvent	Mutable state → immutable event log
reasoning_steps	WorkflowEvent + LlmInvocation	CoT + model tracing unified
(none)	ModelDecision	New: routing decisions recorded
(none)	ArtifactValidation	New: verification evidence tracked
(none)	RecoveryAction	New: failure recovery chain

Next Steps

• Tasks & Attempts — Deep dive into the Task-Attempt lifecycle
• Lineage & Explainability — Tracing artifacts to prompts
• Chain-of-Thought Ledger — The immutable reasoning audit trail