Skip to content

XIOPro Production Blueprint v5.0

Part 3 — Operational Domain Model (ODM)

1. Purpose of This Part

This document defines the Operational Domain Model (ODM) of XIOPro.

It is the single source of truth for:

  • all system entities
  • their relationships
  • their lifecycle
  • their states and transitions
  • how execution is tracked
  • how cost and time are measured
  • how agents interact with work

This is the layer that turns XIOPro from:

"architecture"

into:

an executable system

2. Core Modeling Principles

2.1 Tickets are Truth

  • Tickets define what must be achieved
  • Everything else derives from them

2.2 Tasks are Plan

  • Tasks define how work will be executed

2.3 Activities are Reality

  • Activities define what actually happened

2.4 Knowledge is Persistent

  • Knowledge outlives execution

2.5 State is Explicit

  • Every object MUST have:
  • state
  • status
  • status_state

2.6 Entity Classes

Not every ODM object should be treated the same.

XIOPro should distinguish between:

Lifecycle-Bearing Objects

These are operational objects that actively move through states and statuses.

Examples:

  • project
  • sprint
  • ticket
  • task
  • agent runtime
  • session
  • escalation request
  • research task
  • discussion thread

These objects should normally carry:

  • status
  • state
  • status_state

Durable Decision / Record Objects

These are durable historical or accounting records.

Examples:

  • human decision
  • override record
  • activity evaluation
  • cost ledger entry
  • time ledger entry

These objects do not need full workflow lifecycles unless explicitly required.

They should remain:

  • append-oriented
  • queryable
  • auditable
  • replayable

Persistent Knowledge Objects

These are long-lived knowledge assets.

Examples:

  • rule
  • skill
  • document
  • blueprint
  • reflection

They may have lifecycle state, but they are not live execution actors.

Rule

XIOPro should avoid forcing every object into the same lifecycle model.

Only lifecycle-bearing operational objects should be required to carry full workflow status/state/status_state semantics by default.

2.7 Ticket Numbering

XIOPro uses 4-digit ticket numbering for all new tickets:

  • New tickets start at 1001 and increment
  • Sub-tasks use dot notation: 1001.01, 1001.02, etc.
  • Historical 3-digit tickets (e.g., 069, 072) are preserved as-is and not renumbered
  • Paperclip STR-N format retires when Paperclip is superseded by the ODM work graph

This prevents collision with historical ticket numbers and provides room for growth.

3. Core Entities

The following entities form the core of the ODM. All are defined in detail in Section 4.

flowchart TD
    User --> Idea
    User --> DiscussionThread

    Topic --> Project
    Project --> Sprint
    Sprint --> Ticket
    Ticket --> Task
    Task --> AgentRuntime
    AgentRuntime --> Session
    Session --> Activity
    Activity --> Result
    Result --> Reflection
    Reflection --> Improvement
    Improvement --> Knowledge

    Idea --> DiscussionThread
    DiscussionThread --> Idea
    DiscussionThread --> Ticket
    DiscussionThread --> Task
    Idea --> Ticket

    Task --> EscalationRequest
    EscalationRequest --> HumanDecision
    HumanDecision --> Task

    Task --> ResearchTask
    ResearchTask --> ResearchOutput
    ResearchOutput --> Knowledge

    GovernanceEvent --> OverrideRecord
    OverrideRecord --> Task
    OverrideRecord --> AgentRuntime

3.1 Core Entity List

Entity Class Section
User Lifecycle-Bearing 4.0
Topic Lifecycle-Bearing 4.1
Project Lifecycle-Bearing 4.2
Sprint Lifecycle-Bearing 4.3
Discussion Thread Lifecycle-Bearing 4.3A
Idea Lifecycle-Bearing 4.3B
Ticket Lifecycle-Bearing 4.4
Task Lifecycle-Bearing 4.5
Activity Lifecycle-Bearing 4.6
Activity Evaluation Durable Record 4.6.1
Cost Ledger Entry Durable Record 4.6.2
Time Ledger Entry Durable Record 4.6.3
Agent Template Lifecycle-Bearing 4.7
Agent Runtime Lifecycle-Bearing 4.8
Execution Surface Lifecycle-Bearing 4.9
Session Lifecycle-Bearing 4.10
Escalation Request Lifecycle-Bearing 4.11
Human Decision Durable Record 4.12
Override Record Durable Record 4.12A
Research Task Lifecycle-Bearing 4.12B
Knowledge Object Persistent Knowledge 4.13

4. Entity Definitions

4.0 User

Purpose

Identity and access entity for human operators of XIOPro.

User is a first-class ODM entity because the system must support multiple human operators with distinct roles, permissions, and notification preferences. All ODM entities that reference human identity should reference user_id rather than hardcoding a specific person.

Properties

id: string
name: string
email: string
role: enum
  # founder | operator | reviewer | observer
auth_accounts: [string]
  # Max plan emails (e.g., shai@struxio.ai, dev@struxio.ai)
is_primary: boolean
  # primary decision maker — only one user has this true
notification_channels: [string]
  # sse | email | telegram | slack | webhook
status: enum
  # active | inactive
created_at: datetime

Notes

  • Current user: Shai (founder, primary). The system must support multiple users in the future.
  • is_primary identifies the default decision maker when escalations do not specify a target user.
  • role is a system role, not a job title. "founder" is a role value, not a hardcoded identity.
  • auth_accounts links to the Max/API accounts available for LLM access.
  • notification_channels determines how the user receives alerts, morning briefs, and escalation requests.
  • Other ODM entities that reference humans (e.g., opened_by, created_by, issued_by) should store user_id where practical. Historical text-based references are preserved for backward compatibility.

4.1 Topic

Purpose

Hierarchical knowledge classification system.

Properties

id: string
name: string
parent_topic_id: string|null
related_topics: [topic_id]
taxonomy: [string]
description: string

Notes

  • Forms a tree + graph
  • Drives:
  • agent responsibility
  • knowledge classification
  • search indexing

4.1.1 Topic Enrichment Layer

Purpose

Topics in the ODM define structure.

The Topic Enrichment Layer defines:

  • behavior
  • intelligence
  • execution relevance
  • search optimization

Principle

Base Topic = stored, minimal, stable Enriched Topic = computed, dynamic, intelligent

Enriched Topic Model

topic_enriched:
  id: string

  # Hierarchy (derived)
  path: string
  level: int

  # Graph
  related_topics: [topic_id]

  # Usage metrics
  usage_count: int
  linked_documents: int
  linked_tickets: int

  # Scoring
  importance_score: float
  volatility_score: float

  # Execution binding
  owner_agent: string|null

  # Context
  active_projects: [project_id]

  # Metadata
  last_used: datetime

Computation Flow

flowchart TD
    TopicBase --> EnrichmentEngine
    EnrichmentEngine --> ComputeHierarchy
    EnrichmentEngine --> ComputeUsage
    EnrichmentEngine --> ComputeScores
    EnrichmentEngine --> AssignAgent
    AssignAgent --> EnrichedTopic

Computation Triggers

  • document ingestion (Librarian)
  • ticket creation
  • agent execution
  • Dream Engine cycles
  • search queries

Responsibilities

Component Role
Librarian classification + enrichment
Governor scoring + optimization
Orchestrator execution alignment

Why This Separation Matters

If stored directly in DB:

  • heavy updates
  • rigid structure
  • performance issues

If computed:

  • flexible
  • scalable
  • adaptive

Final Statement

Topics are:

  • stored as structure
  • computed as intelligence

4.1B Host

Purpose

Physical or cloud compute node that runs XIOPro services and agents. Host is a first-class ODM entity because resource awareness is a non-negotiable design constraint (Part 1, Section 4.10).

Properties

id: string
name: string
role: enum
  # control_plane | worker | hybrid | gpu | product
ip_tailscale: string|null
ip_public: string|null
os: string
cpu_model: string
vcpus: int
ram_gb: float
ssd_gb: float
gpu: string|null

reserved_ram_gb: float
available_ram_gb: float
ram_per_agent_gb: float
max_concurrent_agents: int
active_agents: int
active_services: [string]

status: enum
  # online | offline | degraded | maintenance

commissioned_at: datetime
decommissioned_at: datetime|null

Current Hosts (as of 2026-03-28)

Host Role vCPU RAM SSD Est. Max Agents
Hetzner CPX62 control_plane 16 (AMD EPYC-Genoa) 30 GB 150 GB 8-12 agents on current hardware (30GB RAM, ~2GB per agent session + overhead). Scale with additional hosts.
Mac Studio M1 hybrid 8-core CPU + GPU 32 GB 512+ GB ~25 (minimal services overhead)

Notes

  • Agent Runtimes reference their host via host_id
  • the orchestrator checks host capacity before spawning agents (see Part 4, Section 4.2F)
  • the governor monitors host health and triggers breakers on memory pressure
  • New hosts require commissioning: Tailscale, Docker, agent runtime, ODM registration

4.2 Project

Purpose

A bounded initiative (e.g., XIOPro, MVP1).

Each project has its own agent roster — different projects need different specialists, and may have different orchestrators.

Properties

id: string
name: string
parent_project_id: string|null   # nullable FK to projects.id — enables composite projects (see Part 9, Section 5B)
topics: [topic_id]
description: string
start_date: datetime
end_date: datetime|null
lifecycle_phase: enum
  # topic | research | blueprint | review | planning | execution | integration | production | maintenance
state: enum
status: enum
status_state: enum

Composite Projects: When parent_project_id is set, this project is a sub-project of the referenced parent. Sub-projects have their own PO, template, and sprint plan but coordinate through the parent's Master PO. Only one level of nesting is permitted (a sub-project cannot itself be a parent). See Part 9, Section 5B for full rules.

lifecycle_phase tracks which lifecycle gate the project has reached (see Part 9 Section 10). This is distinct from the three-dimensional state model: status/state track workflow position within any phase, while lifecycle_phase tracks the project's position in the Topic-to-Product pipeline.

4.2.1 Project Agent Roster (v5.0 Addition)

Each project maintains a roster of agents assigned to it, with their roles for that specific project.

project_agent_binding:
  id: string
  project_id: string
  agent_id: string
  roles: [string]                    # roles this agent plays IN THIS PROJECT
  allocation: enum
    # full_time | part_time | shared | on_demand
  is_project_orchestrator: boolean   # orchestrates THIS project
  joined_at: datetime
  left_at: datetime|null
Multi-Project Rules
  • An agent can work on multiple projects simultaneously (shared allocation)
  • Each project can have its own orchestrator (not necessarily the system master)
  • The system master can create projects and assign orchestrators
  • Roles are project-scoped: an agent may be a specialist on project A and an orchestrator on project B
  • When the orchestrator assigns a task, it only considers agents on that project's roster
  • Agent capacity (from Host Registry) is shared across all projects — the orchestrator must coordinate
System Master vs Project Orchestrator
# System level — one master oversees everything
system_master_agent_id: string       # can create projects, manage all agents

# Project level — each project has its own orchestrator
project_orchestrator:
  project_id: string
  agent_id: string                   # orchestrates THIS project
  # Can be the same as system master, or a different agent
Example Rosters
# XIOPro project roster
project: XIOPro
roster:
  - agent: 000, roles: [orchestrator, governor], allocation: shared
  - agent: 002, roles: [specialist, coder], allocation: full_time
  - agent: 005, roles: [specialist, ops], allocation: part_time

# MVP1 project roster (different orchestrator possible)
project: MVP1
roster:
  - agent: 000, roles: [orchestrator], allocation: shared
  - agent: 001, roles: [specialist, compliance], allocation: full_time
  - agent: 003, roles: [specialist, designer], allocation: part_time
  - agent: 004, roles: [specialist, analyst], allocation: part_time
  - agent: 010, roles: [worker, ops], allocation: on_demand
Roster Lifecycle

The roster is editable during the project: - Orchestrator adds/removes agents as needs change - Allocation can shift (part_time → full_time during crunch) - New agents can be spawned specifically for a project - When a project completes, its roster is archived (agents freed for other work)

4.3 Sprint

Purpose

Time-boxed execution container.

Properties

id: string
project_id: string
start_date: datetime
end_date: datetime
tickets: [ticket_id]
state: enum
status: enum
status_state: enum

4.3A Discussion Thread

Purpose

Durable intake and clarification object for human-to-system discussion.

A Discussion Thread exists to capture the structured conversation that happens before or alongside formal execution objects.

It bridges:

  • idea formation
  • exploratory conversation
  • clarification
  • user guidance
  • conversion into ticket or task

Properties

id: string
project_id: string|null
topic_ids: [topic_id]

title: string|null
summary: string|null

thread_type: enum
# intake | clarification | design | review | recovery | research

opened_by: string
participants: [string]

source_channel: enum|null
# ui | rc | cli | api | imported

linked_ticket_id: string|null
linked_task_id: string|null
linked_session_id: string|null
idea_ids: [string]
  # many-to-many link to Idea entities — a discussion may relate to multiple ideas

state: enum
# active | waiting | promoted | closed | archived

status: enum
# create | discussion | review | complete | archive

status_state: string

transcript_ref: string|null
context_bundle_ref: string|null

created_at: datetime
updated_at: datetime
closed_at: datetime|null

Notes

  • Discussion Thread is the missing durable object between free-form human interaction and governed work
  • It prevents important clarifications from living only in chat
  • A thread may promote into a Ticket, a Task, or a Research Task
  • It may also remain archival if no formal work object is created
  • Discussion Thread is a core entity, not an auxiliary concept — it appears in flow diagrams and is referenced across Parts 1, 4, and 6
  • A Discussion Thread may be linked to one or more Ideas (many-to-many). Discussions may surface new ideas, and ideas may spawn new discussions.

4.3B Idea

Purpose

First-class ODM entity for capturing thoughts, proposals, and possibilities before they become formal work.

Idea bridges the gap between raw human thought and structured DiscussionThread. It is the earliest durable object in the XIOPro work lifecycle — a thought that deserves to be remembered, reviewed, and eventually acted upon or deliberately set aside.

Properties

id: string
title: string
description: string
topic_id: string
  # one topic per idea — primary classification

source: enum
  # user | agent | dream | research | discussion | external
source_ref: string|null
  # reference to the originating object (e.g., discussion_thread_id, research_task_id)
raised_by_user_id: string|null
  # references User entity — null if raised by agent or system
raised_by_agent_id: string|null
  # 3-digit agent ID if raised by an agent

status: enum
  # new | under_discussion | approved | ticketed | deferred | rejected | archived

discussion_thread_ids: [string]
  # many-to-many — an idea may have multiple discussion threads
ticket_id: string|null
  # set when idea is approved and shaped into a ticket

last_reviewed_at: datetime|null
review_cycle: enum|null
  # weekly | monthly | quarterly | on_demand
next_review_at: datetime|null

priority: enum|null
  # low | normal | high | critical
tags: [string]
context: string|null
  # free-form context, rationale, or background

created_at: datetime
updated_at: datetime
created_by: string

Idea Lifecycle

flowchart TD
    New --> UnderDiscussion
    New --> Deferred
    New --> Rejected
    UnderDiscussion --> Approved
    UnderDiscussion --> Deferred
    UnderDiscussion --> Rejected
    Approved --> Ticketed
    Deferred --> UnderDiscussion
    Deferred --> Rejected
    Deferred --> Archived
    Rejected --> Archived
    Ticketed --> Archived

Notes

  • Idea is a Lifecycle-Bearing Object — it actively moves through statuses
  • An Idea may sit dormant in new or deferred status for weeks or months. Idle Maintenance surfaces stale ideas for review (see Part 4, Idle Maintenance)
  • Ideas with status new or deferred that have not been reviewed within their review_cycle should appear in the morning brief
  • An Idea does not require a DiscussionThread to exist — some ideas are clear enough to be approved directly
  • Multiple Ideas may emerge from a single DiscussionThread (many-to-many)
  • When an Idea is approved and shaped into work, its status becomes ticketed and ticket_id is set
  • Ideas can originate from any source: user thoughts, agent observations, Dream Engine proposals, research outputs, or discussion threads

Idea-Discussion-Ticket Flow

User has a thought → Idea created (status: new, tagged with topic)
  → May sit dormant, reviewed periodically by Idle Maintenance

Idea gets discussed → DiscussionThread created, linked to Idea
  → Discussion may surface MORE ideas (many-to-many)

Decision made:
  → approved → deeper DiscussionThread to shape into work
  → deferred → stays in backlog, reviewed later
  → rejected → archived with reason

Approved idea shaped → DiscussionThread produces Ticket
  → Idea status: ticketed, linked to Ticket

flowchart TD
    Thought["User/Agent has a thought"]
    Thought --> IdeaCreated["Idea created (new)"]
    IdeaCreated --> Dormant["Sits in backlog"]
    Dormant --> IdleMaintenance["Idle Maintenance surfaces it"]
    IdleMaintenance --> DiscussionStarted["DiscussionThread created"]
    IdeaCreated --> DiscussionStarted
    DiscussionStarted --> MoreIdeas["Discussion surfaces new Ideas"]
    MoreIdeas --> IdeaCreated
    DiscussionStarted --> Decision{"Decision"}
    Decision --> Approved["approved"]
    Decision --> Deferred["deferred → back to backlog"]
    Decision --> Rejected["rejected → archived"]
    Deferred --> Dormant
    Approved --> ShapingDiscussion["Deeper DiscussionThread"]
    ShapingDiscussion --> TicketCreated["Ticket created"]
    TicketCreated --> IdeaTicketed["Idea status: ticketed"]

4.4 Ticket

Purpose

The unit of truth for work definition .

Properties

id: string
project_id: string
topics: [topic_id]
title: string
description: string
priority: enum
required_model: string|null
required_skills: [string]

state: enum
status: enum
status_state: enum

tasks: [task_id]

plan_cost: float
actual_cost: float
plan_duration: float
actual_duration: float

Notes

  • Can be split into sub-tickets
  • Can generate tasks automatically
  • Is the reference object for UI and reporting
  • New tickets use 4-digit numbering starting at 1001

4.5 Task

Purpose

Executable plan unit derived from a ticket.

A Task is the primary object used to:

  • define bounded work
  • assign ownership
  • enforce dependencies
  • hold human gates
  • track plan vs actual
  • determine completion state

Properties

id: string
ticket_id: string
parent_task_id: string|null
sequence: int

title: string
objective: string
description: string|null

depends_on: [task_id]
blocks: [task_id]

assigned_agent_template_id: string|null
assigned_runtime_id: string|null
assigned_topic_ids: [topic_id]

execution_mode: enum
# headless | rc_attachable | scheduled | event_driven | interactive

requires_human: boolean
requires_approval: boolean
allows_parallel_subwork: boolean

input_refs: [string]
output_refs: [string]
acceptance_criteria: [string]

priority: enum
risk_level: enum
# low | normal | high | critical

plan_cost: float|null
cost_cap: float|null
actual_cost: float

plan_duration_minutes: float|null
actual_duration_minutes: float
sla_due_at: datetime|null

attempt_count: int
max_attempts: int|null

spec_version: int  # default 1; increments when task description changes
spec_snapshot: jsonb|null  # stores the task spec at time of assignment

state: enum
status: enum
status_state: enum

created_at: datetime
updated_at: datetime
started_at: datetime|null
completed_at: datetime|null

Notes

  • Task is the main planning object beneath a Ticket
  • Task is resumable and re-assignable
  • Human discussion and approval are modeled at Task level first
  • Cost and duration roll upward from Activities into the Task
  • spec_version increments each time the task description, objective, or acceptance criteria change after initial creation. This ensures agents always know which version of the spec they were assigned.
  • spec_snapshot captures the full task spec (title, objective, description, acceptance_criteria) as a JSON object at the moment of assignment. If the task is reassigned or the spec changes, a new snapshot is written. This prevents spec drift between what the agent received and what the task currently says.

4.6 Activity

Purpose

Atomic execution event.

Activity is the smallest accountable runtime record in XIOPro. It captures what actually happened during one execution step.

Properties

id: string
task_id: string
agent_runtime_id: string
session_id: string|null
execution_surface_id: string|null

activity_type: enum
# prompt | tool_call | file_change | code_exec | search | retrieval | evaluation | escalation | approval | recovery | dream

sequence: int
started_at: datetime
ended_at: datetime|null
duration_ms: int|null

input_ref: string|null
output_ref: string|null
artifact_refs: [string]

provider: string|null
model: string|null
auth_mode: enum|null
# subscription | api_key | hybrid

prompt_tokens: int|null
completion_tokens: int|null
cached_tokens: int|null
total_tokens: int|null

estimated_cost: float|null
actual_cost: float|null

result_status: enum
# success | partial | failed | cancelled | blocked

error_code: string|null
error_message: string|null
retryable: boolean

evaluation_ref: string|null
metadata_ref: string|null

created_at: datetime
updated_at: datetime

Notes

  • Activity is the atomic unit for cost, time, and audit
  • Activities must be append-only except for controlled completion updates
  • One Task usually contains many Activities
  • Recovery, escalation, approval, and Dream work are all Activities

4.6.1 Activity Evaluation

Purpose

Structured quality assessment of an activity outcome.

Properties

id: string
activity_id: string
success: boolean
score: float|null
reviewer_type: enum
# system | agent | human

findings: [string]
corrections: [string]
recommended_next_action: string|null

created_at: datetime

Notes

  • Evaluation must not overwrite the raw Activity
  • It supports hindsight, learning, and governance

4.6.2 Cost Ledger Entry

Purpose

Normalized accounting entry linked to an activity.

Properties

id: string
activity_id: string
agent_runtime_id: string|null
task_id: string|null
ticket_id: string|null
project_id: string|null

provider: string|null
model: string|null
charge_type: enum
# tokens | runtime | tool | storage | network | fixed

quantity: float
unit_cost: float
amount: float
currency: string

recorded_at: datetime

Notes

  • Cost Ledger Entry exists so accounting is queryable even when provider formats differ
  • the governor reads this layer for budget enforcement and anomaly detection

4.6.3 Time Ledger Entry

Purpose

Normalized duration and timing record linked to execution.

Properties

id: string
activity_id: string
agent_runtime_id: string|null
task_id: string|null
ticket_id: string|null

started_at: datetime
ended_at: datetime|null
duration_ms: int|null
wait_reason: string|null

recorded_at: datetime

Notes

  • Time Ledger Entry allows queue time, wait time, and active execution time to be analyzed separately
  • Time analysis must support both optimization and SLA tracking

4.6.4 Activity Table Partitioning Strategy

Purpose

The activities table is the highest-volume table in the ODM. Without partitioning, query performance degrades as execution history grows. This section specifies the partitioning strategy.

Partitioning Scheme

  • Partition key: created_at
  • Partition interval: monthly (e.g., activities_2026_03, activities_2026_04)
  • Partition type: PostgreSQL native range partitioning (PARTITION BY RANGE (created_at))

Partition Management

  • Automated creation: a pg_cron job (or the Governor's scheduled sweep) creates the next month's partition at least 7 days before the month boundary
  • Verification: the Governor checks at startup that the current month and next month partitions exist. Missing partitions trigger a critical alert.

Archival Policy

  • Hot storage: partitions for the most recent 6 months remain in the primary PostgreSQL instance
  • Cold storage: partitions older than 6 months are exported to cold storage (Backblaze B2 or equivalent) in pg_dump or CSV format, then detached from the active table
  • Retention: archived partitions are retained in cold storage indefinitely (or per company retention policy)
  • Restore: archived partitions can be re-attached for ad-hoc queries if needed

Index Strategy

Each partition carries its own local indexes:

  • (agent_id, created_at) -- agent activity timeline queries
  • (task_id, created_at) -- task activity timeline queries
  • (activity_type, created_at) -- type-filtered queries (cost, recovery, approval)

Global indexes across all partitions are avoided to maintain partition independence.

Rules

  • All queries against activities must include a created_at range filter to enable partition pruning
  • INSERT operations always target the current partition; the partitioning scheme handles routing automatically
  • The cost_ledger and time_ledger tables follow the same partitioning strategy if they exceed 1M rows

4.7 Agent Template

Purpose

Canonical definition of an agent class.

This defines what an agent is allowed to be and do, but not a specific live running instance.

Properties

id: string
agent_id: string
# 3-digit agent identifier (e.g., "000", "002")
# Maps to the unified agent identity model (see Part 1, Section 8.1)
name: string

roles: [string]
# One or more from role_bundles: orchestrator, governor, rule_steward,
# prompt_steward, module_steward, specialist, worker, interface

is_master: boolean
# Only one agent template has this true (000)

description: string

topics: [topic_id]
responsibilities: [string]
allowed_tools: [string]
required_skills: [string]

# Default LLM / Auth binding
default_provider: string|null
default_model: string|null
default_auth_method: enum|null
# oauth | api_key | litellm
default_auth_account: string|null

execution_modes: [string]
# headless | rc_attachable | scheduled | event_driven | interactive

spawn_policy:
  parent_required: boolean
  max_children: int|null
  max_parallel_runs: int|null

cost_profile:
  priority: enum
  max_cost_per_run: float|null
  preferred_cost_tier: enum|null

source_ref: string|null
version: string

state: enum
status: enum
status_state: enum

created_at: datetime
updated_at: datetime

Notes

  • Agent Template is a design-time object
  • It is reusable across many runtime instances
  • It separates:
  • blueprint identity
  • runtime identity

4.8 Agent Runtime

Purpose

Live instantiated execution actor.

This is the object that actually performs work.

Properties

id: string
agent_template_id: string

agent_id: string
# 3-digit agent identifier (e.g., "000", "002", "101")
# Maps to the unified agent identity model (see Part 1, Section 8.1)

runtime_kind: enum
# orchestrator | specialist | worker | interface | system

parent_runtime_id: string|null
root_runtime_id: string|null
orchestrator_id: string|null
# 3-digit ID of the orchestrator agent (null = I am the master)

assigned_ticket_id: string|null
assigned_task_id: string|null
current_goal: string|null

execution_surface_id: string|null
current_session_id: string|null

# LLM / Auth Binding
provider: string|null
# anthropic | openai | google | local
model: string|null
auth_method: enum|null
# oauth | api_key | litellm
auth_account: string|null
# email for OAuth (e.g., shai@struxio.ai, dev@struxio.ai)
api_key_ref: string|null
# SOPS key reference for API key auth
litellm_model_id: string|null
# LiteLLM model routing ID

host_id: string|null
# References the Host entity (see Section 4.1B)

state: enum
status: enum
status_state: enum
health_state: enum
# healthy | degraded | blocked | failed | recovering

last_heartbeat_at: datetime|null
started_at: datetime|null
ended_at: datetime|null

last_error: string|null
recoverable: boolean

created_at: datetime
updated_at: datetime

Notes

  • Agent Runtime is the execution-time object
  • One Agent Template can have many Agent Runtimes
  • agent_id uses the 3-digit unified agent identity (Part 1, Section 8.1)
  • runtime_kind aligns with role bundles: orchestrator, specialist, worker, interface, system
  • auth_method, auth_account, api_key_ref, and litellm_model_id form the LLM/Auth Binding (Part 1, Section 8.3)
  • This is the correct level for:
  • ownership
  • health
  • live assignment
  • recovery

4.9 Execution Surface

Purpose

Defines where an agent runtime executes.

Examples:

  • Claude Code
  • Codex CLI / app-backed runtime
  • Gemini CLI
  • custom CLI agent
  • API worker
  • local model runtime
  • future web fallback adapter

Properties

id: string
type: enum
# claude_code | codex | gemini_cli | custom_cli | api_worker | local_model | web_fallback

provider: string
node_id: string|null

auth_mode: enum
# subscription | api_key | hybrid

endpoint_ref: string|null
workspace_ref: string|null

supports_headless: boolean
supports_rc: boolean
supports_resume: boolean
supports_mcp: boolean

state: enum
status: enum
status_state: enum

created_at: datetime
updated_at: datetime

Notes

  • Execution Surface is not the agent itself
  • It is the runtime venue
  • This keeps provider independence explicit

4.10 Session

Purpose

Durable execution session container.

A session is the unit used for:

  • continuity
  • transcript persistence
  • recovery
  • RC attach
  • resume

Properties

id: string
agent_runtime_id: string
execution_surface_id: string

external_session_ref: string|null
external_thread_ref: string|null

state: enum
# active | idle | paused | waiting | blocked | crashed | recovering | closed | archived

status: enum
status_state: enum

opened_by: string|null
context_snapshot_ref: string|null
transcript_ref: string|null
checkpoint_ref: string|null

last_checkpoint_at: datetime|null
last_activity_at: datetime|null

created_at: datetime
updated_at: datetime

Notes

  • Session must be separable from the agent runtime
  • A runtime may move across sessions over time
  • A session may be resumed or replaced

4.11 Escalation Request

Purpose

Structured request for human discussion, clarification, or approval.

This is the ODM object behind RC-triggered human intervention.

Properties

id: string
agent_runtime_id: string
session_id: string|null

ticket_id: string|null
task_id: string|null
activity_id: string|null

trigger_type: enum
# requires_human | requires_approval | ambiguity | failure | manual

urgency: enum
# low | normal | high | critical

summary: string
questions: [string]
options: [string]
recommended_option: string|null

context_bundle_ref: string|null

state: enum
# queued | waiting | active | responded | expired | cancelled | completed | archived

status: enum
# create | discussion | approval | complete | archive

status_state: string

created_at: datetime
resolved_at: datetime|null

Notes

  • This prevents human interaction from living only inside chat
  • It makes approvals and clarifications queryable

4.12 Human Decision

Purpose

Persistent human response to an escalation request.

Properties

id: string
escalation_request_id: string

decision_type: enum
# answer | approve | reject | redirect | constrain | postpone

selected_option: string|null
message: string|null
constraints: [string]

applies_to_runtime_id: string|null
applies_to_task_id: string|null

created_by: string
created_at: datetime

Notes

  • Human Decision is a first-class operational object
  • It must be traceable and replayable
  • Human Decision is a Durable Record object — it is append-only and does not carry full workflow lifecycle semantics

4.12A Override Record

Purpose

Durable record of a human or governed override applied to live execution.

Override Record exists so interventions do not disappear into logs or chat.

Properties

id: string
scope_type: enum
# task | agent_runtime | session | escalation_request | module_route | policy

scope_ref: string
trigger_ref: string|null
# alert / breaker / escalation / manual request

override_type: enum
# pause | resume | constrain | reroute | force_module | force_surface | bypass | cancel

reason: string
issued_by: string
approved_by: string|null

prior_state_ref: string|null
applied_change_ref: string|null

# Explicit override details
override_params: jsonb|null
# Structured parameters of the override (e.g., new module, new surface, constraint values)

effective_from: datetime
effective_until: datetime|null
# Temporal scope of the override

revoked: boolean
revoked_by: string|null
revoked_at: datetime|null

created_at: datetime
expires_at: datetime|null
resolved_at: datetime|null

Notes

  • Override Record is a durable operational record, not a workflow object
  • It supports auditability, replay, and postmortem analysis
  • It is closely related to governance, approvals, and recovery
  • The override_params field stores structured details of what was changed
  • Temporal fields (effective_from, effective_until) allow time-bounded overrides
  • Revocation fields support explicit undo tracking

4.12B Research Task

Purpose

Schedulable and auditable operational research work unit.

Research Task is the runtime/operational counterpart to the Research Center concepts described elsewhere.

Properties

id: string
project_id: string|null
ticket_id: string|null
parent_task_id: string|null

name: string
objective: string
topic_ids: [topic_id]
source_classes: [string]

output_type: enum
# digest | comparison | watchlist | synthesis | presentation | candidate_scan

review_required: boolean
owner_runtime_id: string|null

recurrence: string|null
destination_refs: [string]

state: enum
# draft | queued | active | waiting | blocked | completed | cancelled | archived

status: enum
# create | ready | execute | review | complete | archive

status_state: string

latest_output_ref: string|null
created_at: datetime
updated_at: datetime
completed_at: datetime|null

Notes

  • Research Task is not merely a knowledge note
  • It is an operational object that can be scheduled, executed, reviewed, and linked to tickets/tasks
  • Research outputs may later be promoted into Knowledge Objects through Librarian discipline
  • Research Task is a core entity — it is referenced in Parts 5 and 9 and appears in the execution hierarchy

4.13 Knowledge Object

Purpose

Persistent intelligence artifact.

Unlike Agent Runtime, this object is durable knowledge, not a live execution actor.

Properties

id: string
type: enum
# rule | skill | document | blueprint | reflection | profile | log | research_output

topics: [topic_id]
source: string

content_ref: string
version: string

state: enum
status: enum
status_state: enum

created_at: datetime
updated_at: datetime

Notes

  • Knowledge Objects outlive execution
  • Agents use knowledge, but are not knowledge objects
  • This separation is mandatory for a buildable runtime model

4.14 User ToDo (Attention Queue Item)

Purpose

Lightweight action item requiring human attention.

User Todos are the Attention Queue -- the primary surface where XIOPro communicates what it needs from the user. They are not just manually created; the system auto-generates todos when conditions require human attention, and auto-dismisses them when those conditions clear.

Entity Class

Durable Decision / Record Object.

User Todos do not carry full workflow lifecycle semantics. They are append-oriented, queryable, and auto-revolving.

Properties

id: uuid (primary key, auto-generated)
title: string (required)
description: string (optional, expandable detail)
priority: enum (critical | high | medium | low)
status: enum (open | in_progress | done | dismissed)
environment: string (optional: dns, github, hetzner, paperclip, devxio, bus, etc.)
linked_type: string (optional: escalation, alert, agent, task, approval, budget)
linked_id: string (optional: ID of the source object)
linked_url: string (optional: clickable link to the source object)
assigned_to: string (default: shai)
created_by: string (system | GO | agent_name)
created_at: datetime
completed_at: datetime (auto-set when status becomes done or dismissed)
sort_order: int (manual reordering within priority bands)

Auto-Generation Contract

The Bus runs a 60-second interval scan that creates todos from:

  • pending escalations
  • active critical/warning alerts
  • agents in error state
  • stale tasks (in_progress > 24 hours)
  • budget approaching threshold
  • pending approvals

Dedup key: linked_type + linked_id. No duplicate is created if an open todo already exists for the same linked object.

Auto-Dismiss Contract

When a linked condition clears:

  • escalation resolved -> todo marked done
  • alert acknowledged -> todo marked done
  • agent recovered from error -> todo marked done

Auto-dismissed todos include a reason annotation in their description.

Notes

  • User Todos live in the Bus database (not the XIOPro ODM database) because they are a Bus-level coordination primitive
  • The UI Attention Queue Widget reads from this entity
  • System-generated todos use created_by = 'system' to distinguish from manual todos

5. State Model

5.1 Modeling Principle

Every operational entity must carry three dimensions:

  • status = what phase of work it is in
  • state = its current condition
  • status_state = their combined queryable expression

This allows:

  • deterministic orchestration
  • explicit human gates
  • recovery logic
  • consistent UI and CLI rendering
  • governance enforcement

5.2 Global Status Vocabulary

status:
  - create
  - plan
  - ready
  - execute
  - review
  - test
  - discussion
  - approval
  - recover
  - complete
  - archive

Meaning

  • create -> object is being introduced
  • plan -> being structured/prepared
  • ready -> eligible to start
  • execute -> actively running work
  • review -> being evaluated
  • test -> validation phase
  • discussion -> waiting for or performing human discussion
  • approval -> waiting for formal go/no-go
  • recover -> restoration / retry / repair path
  • complete -> execution finished
  • archive -> retained but inactive

5.3 Global State Vocabulary

state:
  - draft
  - queued
  - ready
  - active
  - paused
  - waiting
  - blocked
  - retry
  - rework
  - failed
  - completed
  - cancelled
  - archived

Meaning

  • draft -> not yet operational
  • queued -> scheduled but not started
  • ready -> immediately runnable
  • active -> currently in progress
  • paused -> intentionally halted
  • waiting -> waiting on dependency / human / external event
  • blocked -> cannot continue
  • retry -> retry scheduled or underway
  • rework -> returned for correction
  • failed -> terminal failure for current attempt
  • completed -> done successfully
  • cancelled -> intentionally stopped
  • archived -> inactive retained history

5.4 Status-State Rules

Allowed Pattern

status expresses workflow phase. state expresses runtime condition.

Examples:

  • execute + active
  • discussion + waiting
  • approval + waiting
  • recover + retry
  • complete + completed

Invalid Pattern Examples

  • complete + active
  • create + completed
  • archive + active

Rule

status_state must always be derivable as:

status_state: "<status>.<state>"

Example:

status: execute
state: active
status_state: execute.active

5.5 Entity-Specific Lifecycle Sets

5.5.1 Ticket Lifecycle

ticket_status:
  - create
  - plan
  - ready
  - execute
  - review
  - approval
  - complete
  - archive

ticket_state:
  - draft
  - queued
  - ready
  - active
  - waiting
  - blocked
  - rework
  - completed
  - cancelled
  - archived

Typical Flow

flowchart TD
    Create --> Plan
    Plan --> Ready
    Ready --> Execute
    Execute --> Review
    Review --> Approval
    Approval --> Complete
    Review --> Rework
    Rework --> Execute
    Complete --> Archive

5.5.2 Task Lifecycle

task_status:
  - create
  - plan
  - ready
  - execute
  - discussion
  - approval
  - review
  - test
  - recover
  - complete

task_state:
  - draft
  - queued
  - ready
  - active
  - paused
  - waiting
  - blocked
  - retry
  - rework
  - failed
  - completed
  - cancelled

Typical Flow

flowchart TD
    Create --> Plan
    Plan --> Ready
    Ready --> Execute
    Execute --> Discussion
    Discussion --> Execute
    Execute --> Approval
    Approval --> Execute
    Execute --> Review
    Review --> Test
    Test --> Complete
    Execute --> Recover
    Recover --> Execute
    Review --> Rework
    Rework --> Execute
    Recover --> Failed

Notes

A task is the main object that pauses for:

  • human discussion
  • approval
  • dependency wait
  • recovery

5.5.3 Agent Runtime Lifecycle

agent_runtime_status:
  - create
  - ready
  - execute
  - discussion
  - recover
  - complete
  - archive

agent_runtime_state:
  - queued
  - ready
  - active
  - paused
  - waiting
  - blocked
  - retry
  - failed
  - completed
  - cancelled
  - archived

Typical Flow

flowchart TD
    Spawn --> Ready
    Ready --> Active
    Active --> Waiting
    Waiting --> Active
    Active --> Paused
    Paused --> Active
    Active --> Recover
    Recover --> Retry
    Retry --> Active
    Recover --> Failed
    Active --> Completed
    Completed --> Archived

Notes

Agent Runtime is the object that captures:

  • execution ownership
  • health
  • assignment
  • retry
  • live failure state

5.5.4 Session Lifecycle

session_status:
  - create
  - ready
  - execute
  - discussion
  - recover
  - complete
  - archive

session_state:
  - queued
  - active
  - idle
  - paused
  - waiting
  - blocked
  - crashed
  - recovering
  - closed
  - archived

Typical Flow

flowchart TD
    Start --> Active
    Active --> Idle
    Idle --> Active
    Active --> Paused
    Paused --> Active
    Active --> WaitingHuman
    WaitingHuman --> Active
    Active --> Crashed
    Crashed --> Recovering
    Recovering --> Active
    Active --> Closed
    Closed --> Archived

Notes

This aligns the ODM with Part 4 Session Manager and RC:

  • a session is durable
  • a session may crash independently
  • a session may wait for human input
  • a session may be resumed or replaced

5.5.5 Escalation Request Lifecycle

escalation_status:
  - create
  - discussion
  - approval
  - complete
  - archive

escalation_state:
  - queued
  - waiting
  - active
  - responded
  - expired
  - cancelled
  - completed
  - archived

Typical Flow

flowchart TD
    Create --> Waiting
    Waiting --> HumanResponds
    HumanResponds --> Responded
    Responded --> Completed
    Waiting --> Expired
    Waiting --> Cancelled
    Completed --> Archived

Notes

This is the durable operational object behind:

  • RC discussion
  • approval requests
  • clarifications
  • founder interventions

5.5.6 Human Decision Lifecycle

Human Decision is a Durable Record object.

It does not carry full workflow lifecycle semantics. A Human Decision is created once in response to an Escalation Request and is immutable after creation.

human_decision:
  # No status/state lifecycle — append-only record
  # Created when human responds to an escalation
  # Immutable after creation

This is consistent with the Entity Class distinction in Section 2.6: Human Decision is a Durable Decision / Record Object, not a Lifecycle-Bearing Object.

5.5.7 Knowledge Object Lifecycle

knowledge_status:
  - create
  - review
  - ready
  - archive

knowledge_state:
  - draft
  - ready
  - rework
  - archived

Typical Flow

flowchart TD
    Create --> Review
    Review --> Ready
    Review --> Rework
    Rework --> Review
    Ready --> Archive

Notes

Knowledge objects are persistent and slow-moving compared to runtime entities.

5.5.8 Discussion Thread Lifecycle

discussion_thread_status:
  - create
  - discussion
  - review
  - complete
  - archive

discussion_thread_state:
  - active
  - waiting
  - promoted
  - closed
  - archived

Typical Flow

flowchart TD
    Create --> Active
    Active --> Waiting
    Waiting --> Active
    Active --> Review
    Review --> Promoted
    Review --> Closed
    Promoted --> Archived
    Closed --> Archived

Notes

  • A Discussion Thread may be promoted into a Ticket, Task, or Research Task
  • Promotion does not delete the thread — it transitions to promoted state and retains the full transcript

5.5.9 Idea Lifecycle

idea_status:
  - new
  - under_discussion
  - approved
  - ticketed
  - deferred
  - rejected
  - archived

Typical Flow

flowchart TD
    New --> UnderDiscussion
    New --> Deferred
    UnderDiscussion --> Approved
    UnderDiscussion --> Deferred
    UnderDiscussion --> Rejected
    Approved --> Ticketed
    Deferred --> UnderDiscussion
    Rejected --> Archived
    Ticketed --> Archived
    Deferred --> Archived

Notes

  • Idea uses a custom status set rather than the global devxio_status vocabulary, because its lifecycle is distinct from execution objects
  • new and deferred ideas are candidates for Idle Maintenance review
  • Transition from deferred back to under_discussion enables periodic re-evaluation

5.5.10 Research Task Lifecycle

research_task_status:
  - create
  - ready
  - execute
  - review
  - complete
  - archive

research_task_state:
  - draft
  - queued
  - active
  - waiting
  - blocked
  - completed
  - cancelled
  - archived

Typical Flow

flowchart TD
    Create --> Ready
    Ready --> Execute
    Execute --> Review
    Review --> Complete
    Review --> Rework
    Rework --> Execute
    Complete --> Archive

Notes

  • Research Task follows the same lifecycle pattern as Task but with a simplified status set
  • Recurring research tasks return to ready after completion of each cycle

5.6 Human Gate Semantics

Discussion and approval are not side effects.

They are stateful control points.

Discussion Gate

Used when:

  • ambiguity exists
  • founder clarification is required
  • tradeoff decision is needed

Expected pattern:

status: discussion
state: waiting

Approval Gate

Used when:

  • execution is risky
  • policy requires founder sign-off
  • system change would alter behavior

Expected pattern:

status: approval
state: waiting

Resume Rule

Once a Human Decision is recorded, the blocked entity transitions back to one of:

  • execute.ready
  • execute.active
  • review.ready
  • complete.completed
  • cancelled

5.7 Recovery Semantics

Recovery must be explicit and queryable.

Typical recovery states:

recover.ready
recover.retry
recover.failed

Recovery may be triggered by:

  • provider error
  • session crash
  • agent failure
  • network interruption
  • invalid output
  • governance breaker intervention

Recovery may result in:

  • retry same runtime
  • switch session
  • switch surface
  • switch model
  • escalate to human
  • fail terminally

6. Lifecycle Flow

6.1 Core Execution Flow

flowchart TD
    Idea --> Ticket
    Ticket --> Task
    Task --> AgentRuntime
    AgentRuntime --> Session
    Session --> Activity
    Activity --> Result
    Result --> Reflection
    Reflection --> Improvement
    Improvement --> Knowledge

This is the canonical lifecycle spine of XIOPro.

6.2 Human-in-the-Loop Flow

flowchart TD
    TaskActive --> EscalationRequest
    EscalationRequest --> HumanDecision
    HumanDecision --> TaskResume
    TaskResume --> AgentRuntime

This ensures that human intervention becomes persistent system state, not ephemeral chat behavior.

6.3 Recovery Flow

flowchart TD
    Execute --> FailureDetected
    FailureDetected --> RecoverState
    RecoverState --> RetrySameSession
    RecoverState --> ResumeNewSession
    RecoverState --> SwitchSurface
    RecoverState --> HumanEscalation
    RetrySameSession --> Execute
    ResumeNewSession --> Execute
    SwitchSurface --> Execute

This aligns ODM lifecycle with the execution and session recovery requirements.

6.4 Dream / Idle Flow

flowchart TD
    SessionIdle --> DreamEligible
    DreamEligible --> DreamCycle
    DreamCycle --> KnowledgeUpdate
    KnowledgeUpdate --> IndexRefresh
    IndexRefresh --> ReadyState

This allows idle-time intelligence work without confusing it with active task execution.

7. Cost Model

7.1 Purpose

Cost in XIOPro must be:

  • explicit
  • attributable
  • queryable
  • enforceable
  • optimizable

Cost is not a report-only concern. It is part of runtime control.

7.2 Cost Propagation

flowchart TD
    Activity --> Session
    Activity --> AgentRuntime
    Activity --> Task
    Session --> Task
    AgentRuntime --> Task
    Task --> Ticket
    Ticket --> Sprint
    Sprint --> Project
    Project --> Portfolio

Rule

  • Activity is the atomic execution-cost unit
  • Session accumulates session-scoped cost
  • Agent Runtime accumulates runtime-scoped cost
  • Task is the operational budgeting unit
  • Ticket is the business reporting unit
  • Project is the strategic budgeting unit

7.3 Cost Dimensions

cost_dimensions:
  model_cost: float
  tool_cost: float
  infra_cost: float
  storage_cost: float
  human_review_cost: float
  total_cost: float

Notes

  • model_cost = model/provider usage
  • tool_cost = external tools / APIs / MCP actions when billed
  • infra_cost = runtime compute allocation if tracked
  • storage_cost = storage/indexing/retention allocation if tracked
  • human_review_cost = optional operational costing for founder/operator interventions
  • total_cost = canonical sum

7.4 Planned vs Actual Cost

All work-bearing entities should support:

plan_cost: float|null
actual_cost: float|null
cost_variance: float|null
cost_variance_pct: float|null
budget_policy_id: string|null
budget_status: enum|null
# within_budget | warning | exceeded | blocked

Rule

  • plan_cost belongs at least on Task and Ticket
  • actual_cost is aggregated upward from Activities, Sessions, and Agent Runtimes
  • budget_status is queryable and governance-visible

7.5 Activity Cost Schema

activity_cost:
  model_provider: string|null
  model_name: string|null
  auth_mode: enum|null
  # subscription | api_key | hybrid

  prompt_tokens: int|null
  completion_tokens: int|null
  cached_tokens: int|null
  total_tokens: int|null

  model_cost: float|null
  tool_cost: float|null
  infra_cost: float|null
  total_cost: float

  cost_recorded_at: datetime

Notes

This allows XIOPro to compare:

  • provider surfaces
  • subscription vs API execution
  • model efficiency
  • execution venue cost

7.6 Cost Policy Hooks

Cost model must support governance hooks:

cost_policy_hooks:
  soft_limit: float|null
  hard_limit: float|null
  warning_threshold_pct: float|null
  breaker_policy_id: string|null
  escalation_required: boolean

Actions triggered by policy

  • continue
  • warn
  • downgrade model
  • pause execution
  • require approval
  • re-route runtime
  • stop execution

8. Time Model

8.1 Purpose

Time must be modeled with the same rigor as cost.

This enables:

  • scheduling
  • SLA tracking
  • delay detection
  • recovery analysis
  • throughput optimization

8.2 Time Propagation

flowchart TD
    Activity --> Session
    Activity --> AgentRuntime
    Activity --> Task
    Task --> Ticket
    Ticket --> Sprint
    Sprint --> Project

Rule

Atomic time is recorded at Activity. Aggregates flow upward.

8.3 Planned vs Actual Time

time_tracking:
  plan_duration_sec: int|null
  actual_duration_sec: int|null
  queue_duration_sec: int|null
  wait_duration_sec: int|null
  active_duration_sec: int|null
  pause_duration_sec: int|null
  recovery_duration_sec: int|null
  duration_variance_sec: int|null

Notes

This distinguishes:

  • actual work time
  • waiting time
  • human-gate delay
  • recovery overhead

8.4 Execution Timing Markers

All runtime-bearing entities should support applicable markers:

execution_timestamps:
  created_at: datetime
  scheduled_for: datetime|null
  queued_at: datetime|null
  started_at: datetime|null
  paused_at: datetime|null
  resumed_at: datetime|null
  waiting_since: datetime|null
  completed_at: datetime|null
  failed_at: datetime|null
  archived_at: datetime|null

8.5 Time Health

time_health:
  sla_target_sec: int|null
  sla_status: enum|null
  # on_track | at_risk | breached
  delay_reason: string|null
  delay_category: enum|null
  # dependency | human_wait | provider | infra | retry | unknown

9. Human Interaction Model

9.1 Principle

Human interaction must never exist only as chat residue.

It must be modeled as durable operational state.

9.2 Human Gate Triggers

Human interaction may be triggered by:

  • requires_human = true
  • requires_approval = true
  • ambiguity detected
  • policy breaker triggered
  • failure with uncertain recovery path
  • manual founder intervention

9.3 Canonical Flow

flowchart TD
    TaskActive --> EscalationRequest
    EscalationRequest --> DiscussionOrApproval
    DiscussionOrApproval --> HumanDecision
    HumanDecision --> SessionResume
    SessionResume --> TaskContinue

9.4 Human Interaction Binding

human_interaction_binding:
  escalation_request_id: string|null
  human_decision_id: string|null
  session_id: string|null
  rc_attached: boolean
  requires_founder: boolean
  responded_at: datetime|null

Notes

This allows the system to answer:

  • what was waiting on a human
  • who answered
  • where the answer applied
  • whether the runtime resumed

9.5 Approval Semantics

Approval is stronger than discussion.

Approval must support:

approval_contract:
  approval_required: boolean
  approval_scope: enum|null
  # task | ticket | runtime_switch | policy_override | rule_change | dream_output
  approval_state: enum|null
  # not_required | waiting | approved | rejected | expired
  approval_expires_at: datetime|null

10. Runtime Interaction Model

10.1 Principle

XIOPro runtime interaction must be provider-independent and queryable.

The ODM therefore models interaction through runtime entities, not through vendor-specific chat assumptions.

10.2 Canonical Runtime Flow

flowchart TD
    Orchestrator["Orchestrator"] --> AgentRuntime
    AgentRuntime --> ExecutionSurface
    AgentRuntime --> Session
    Session --> Activity
    Activity --> Result
    Result --> Reflection
    Reflection --> Improvement
    Improvement --> KnowledgeObject
    Governor["Governor"] --> AgentRuntime
    Governor --> Session
    Governor --> Activity

10.3 Runtime Relationships

runtime_relationships:
  task_to_runtime: one_to_many
  runtime_to_session: one_to_many
  session_to_activity: one_to_many
  activity_to_result: one_to_one_or_many
  result_to_reflection: zero_to_many
  reflection_to_improvement: zero_to_many
  improvement_to_knowledge_object: zero_to_many

10.4 Coordination Semantics

Coordination must support:

  • orchestrator -> domain runtime delegation
  • parent runtime -> worker runtime spawning
  • runtime -> session transfer
  • runtime -> human escalation
  • governor -> runtime intervention

10.5 Runtime Intervention Modes

runtime_intervention:
  mode: enum
  # continue | pause | reroute | retry | escalate | terminate
  initiated_by: enum
  # system | orchestrator | governor | human
  reason: string|null

11. Ticket Evolution Model

11.1 Principle

Tickets are truth objects, but truth objects may evolve without losing lineage.

11.2 Allowed Evolution Actions

ticket_evolution_action:
  - split
  - spawn_subticket
  - merge
  - reassign
  - defer
  - cancel
  - revive

11.3 Evolution Record

ticket_evolution:
  id: string
  source_ticket_id: string
  action: enum
  target_ticket_ids: [string]
  reason: string
  initiated_by: enum
  # human | orchestrator | governor | system
  created_at: datetime

Notes

This prevents lineage loss when work changes structure.

11.4 Task Evolution

Tasks may:

  • split
  • reorder
  • reassign
  • re-scope
  • return to rework
  • be replaced by a new execution path

Task evolution must preserve:

  • parent ticket link
  • dependency integrity
  • cost/time history
  • audit trace

12. Metadata Layer

12.1 Principle

All ODM entities must support a minimum shared metadata contract.

Metadata is not the business object itself, but it is required for governance, search, and explainability.

12.2 Shared Metadata Contract

metadata:
  created_by: string|null
  created_at: datetime
  updated_by: string|null
  updated_at: datetime

  notes: string|null
  tags: [string]
  labels: [string]

  source_system: string|null
  source_ref: string|null
  correlation_id: string|null
  idempotency_key: string|null

12.3 Operational Metadata Contract

For runtime-bearing entities:

operational_metadata:
  environment: string|null
  node_id: string|null
  workspace_ref: string|null
  branch_ref: string|null
  runbook_ref: string|null
  policy_refs: [string]

12.4 Searchability Rule

Metadata fields used for:

  • filtering
  • governance
  • routing
  • audit
  • indexing

must remain structured and queryable, not buried inside free text.

13. DDL Reference

The YAML pseudoschemas in this document define the logical domain model.

For the executable PostgreSQL schema, see:

resources/SCHEMA_walking_skeleton_v4_2.sql

The DDL file is the authoritative implementation of the ODM for T1P. It must remain synchronized with the entity definitions in this document.

When conflicts exist between this document and the DDL, the DDL is authoritative for column types and constraints, while this document is authoritative for entity semantics and lifecycle rules.

14. Storage Strategy

14.1 Principle

Storage in XIOPro is multi-layered. Different data types belong in different stores.

14.2 Canonical Storage Layers

DB (Primary Operational Store)

Stores:

  • ODM entities
  • relationships
  • states
  • costs
  • schedules
  • runtime references
  • governance references

Markdown / Git (Canonical Human-Readable Knowledge)

Stores:

  • blueprints
  • rules
  • skills
  • human-authored system documents
  • structured knowledge artifacts

Object / Blob Storage

Stores:

  • transcript snapshots
  • large outputs
  • exported artifacts
  • checkpoints
  • logs requiring retention

Derived Index Layer

Stores:

  • search index entries
  • embeddings / vector entries if enabled
  • retrieval summaries
  • classification outputs

14.3 Storage Binding Rule

ODM entities should avoid storing heavy payloads directly.

Use references:

storage_binding:
  content_ref: string|null
  transcript_ref: string|null
  checkpoint_ref: string|null
  blob_ref: string|null

14.4 System of Record Rule

  • operational truth = DB
  • knowledge source of truth = Markdown/Git
  • large binary or transcript payload = object storage
  • retrieval acceleration = index layer

This avoids mixing execution state with document source truth.

14A. Execution Report (Derived View) — v5.0 Addition

Purpose

The Execution Report is not a stored entity. It is a derived view assembled from ODM tables on demand or on schedule.

It replaces manual status documents (like Part 11 during bootstrap) with live, queryable, automatable reports.

Data Sources

Report Section ODM Source Table Query Pattern
Completed work activities Filter by timeframe, join to tasks/tickets
Decisions made human_decisions Filter by timeframe
Interventions override_records Filter by timeframe
Open/blocked items tasks WHERE status NOT IN ('completed', 'cancelled')
Ticket progress tickets Aggregate by status, join to sprint
Agent utilization agent_runtimes + activities Active time, idle time, cost per agent
Infrastructure health hosts Status, RAM usage, active agents
Cost summary cost_ledger SUM by agent, task, ticket, sprint
Time summary time_ledger SUM by agent, task, ticket
Knowledge changes Knowledge Ledger Filter by timeframe
Alerts Governance alerts Active, acknowledged, resolved
Escalations escalation_requests Open, waiting, resolved

Timeframes

execution_report_timeframes:
  - realtime     # SSE push to UI — live activity feed
  - hourly       # On-demand or scheduled — hour delta
  - session      # SessionEnd hook — session summary
  - daily        # 06:00 UTC cron — morning brief for founder
  - sprint       # Sprint close — full retrospective
  - custom       # Any from/to range

API

endpoint: GET /reports/execution-summary
parameters:
  timeframe: enum     # realtime | hourly | session | daily | sprint | custom
  from: datetime      # for custom range
  to: datetime        # for custom range
  format: enum        # markdown | json | html
  agent_id: string    # optional filter
  ticket_id: string   # optional filter

response:
  activities: [activity_summary]
  decisions: [decision_summary]
  open_items: [task_summary]
  ticket_progress: {done: N, in_progress: N, blocked: N, todo: N}
  cost: {total_usd: float, by_agent: {}, by_ticket: {}}
  infrastructure: {hosts: [...], alerts: [...]}
  knowledge_changes: [ledger_entry_summary]

Delivery

Delivery Mechanism Trigger
UI widget SSE push → Control Center dashboard Real-time (every activity)
Morning brief Scheduled job → Bus push to founder SSE Daily 06:00 UTC
Session summary SessionEnd hook → write to markdown + push On session end
Sprint retro Manual trigger or sprint close On demand
Obsidian note Agent writes daily note to vault Daily after morning brief

Rule

The Execution Report is the primary mechanism by which the founder maintains visibility without attending every agent session.

When the ODM is operational, Part 11 (manual execution log) is superseded by this automated view.

15. Scheduler Model

15.1 Scheduling Modes

schedule_mode:
  - immediate
  - delayed
  - periodic
  - event_driven
  - idle_window

Meaning

  • immediate = run now
  • delayed = run at specific time
  • periodic = repeat on schedule
  • event_driven = run when trigger occurs
  • idle_window = run only during eligible low-activity period

15.2 Scheduling Schema

schedule:
  mode: enum
  run_at: datetime|null
  cron_expr: string|null
  timezone: string|null
  dependency_event: string|null
  idle_policy_id: string|null
  max_delay_sec: int|null

15.3 Dream Alignment

idle_window is the required scheduling mode for Dream-type work.

This keeps Dream execution separate from active ticket execution.

16. Hindsight / Learning Support

16.1 Principle

Activities must produce evaluation-ready traces.

Learning is impossible if execution cannot be scored and explained.

16.2 Activity Evaluation Contract

evaluation:
  success: boolean|null
  score: float|null
  confidence: float|null

  quality_notes: string|null
  failure_reason: string|null
  retry_recommended: boolean|null
  human_correction_required: boolean|null

  evaluator_type: enum|null
  # agent | human | governor | test_system
  evaluated_at: datetime|null

16.3 Reflection and Improvement Linkage

flowchart TD
    Activity --> Evaluation
    Evaluation --> Reflection
    Reflection --> Improvement
    Improvement --> RuleUpdate
    Improvement --> SkillUpdate
    Improvement --> RoutingUpdate
    Improvement --> KnowledgeUpdate

16.4 Learning Outputs

Learning support should enable:

  • agent quality scoring
  • repeated-failure detection
  • rule refinement suggestions
  • skill improvement suggestions
  • provider routing optimization
  • Dream Engine consolidation inputs

16.5 Non-Negotiable Rule

No important execution may remain as unstructured chat residue.

If it matters, it must become one or more of:

  • activity
  • evaluation
  • reflection
  • improvement
  • knowledge object

17. Current State

As of 2026-03-28, ODM entities exist primarily as:

  • Paperclip tickets (STR-N format, to be migrated to 4-digit numbering)
  • Bus messages (PostgreSQL-backed)
  • State files (plan.yaml, next-actions.yaml)
  • Hindsight memory blocks

The walking skeleton DDL (resources/SCHEMA_walking_skeleton_v4_2.sql) will be the first executable implementation of the full ODM in PostgreSQL.

18. ODM Success Criteria

ODM is successful if:

  • system is queryable
  • state is explicit
  • cost is traceable
  • execution is reproducible
  • agents are controlled

19. Dual-Database Architecture

XIOPro uses two PostgreSQL databases. This is a deliberate architectural choice, not an accident.

19.1 Database Inventory

Database Owner Contents Migration Ownership
bus Bus MCP server agent_registry, events, messages, go_lease, host_capacity, Bus-internal tables Bus service manages its own migrations via its deploy scripts
devxio XIOPro Walking Skeleton ODM tables (projects, tickets, tasks, sessions, agent_runtimes, cost_ledger, etc.) Managed by Alembic migrations in the walking skeleton repo

19.2 Why Two Databases

The Bus is a standalone MCP service that can be deployed independently of XIOPro. It has its own schema, its own migration lifecycle, and its own deployment cadence. Merging Bus tables into the ODM database would create a tight coupling that violates the Bus's independence.

19.3 Cross-Database Relationship

The two databases relate through a shared identifier:

  • bus.agent_registry.id maps to devxio.agent_runtimes.agent_id
  • The Bus knows which agents exist and their liveness state
  • The ODM knows the agent's runtime history, cost, and task assignments
  • No foreign keys cross the database boundary. The relationship is maintained by convention and validated by the Governor

19.4 Operational Rules

  • Bus migrations are never run by the walking skeleton. The Bus deploy process handles them.
  • ODM migrations are never run by the Bus. Alembic handles them.
  • Agents access both databases through the Bus API (the Bus proxies ODM queries where needed).
  • Direct cross-database joins are prohibited. If a query needs data from both, it must make two API calls and join in application code.

20. Final Statement

ODM is the nervous system of XIOPro .

If done correctly:

  • XIOPro becomes buildable
  • agents become reliable
  • execution becomes measurable
  • intelligence compounds

If done poorly:

  • chaos returns
  • cost explodes
  • system collapses

Changelog

v5.0.0 (2026-03-28)

Changes from v4.1.0:

  • C3.1: Moved DiscussionThread to core entity list (Section 3.1) with explicit table entry and added lifecycle (Section 5.5.8). Added note to 4.3A emphasizing its core status.
  • C3.2: Moved ResearchTask to core entity list (Section 3.1) with explicit table entry and added lifecycle (Section 5.5.9). Added note to 4.12B emphasizing its core status.
  • C3.3: Expanded OverrideRecord schema (Section 4.12A) with override_params, effective_from, effective_until, and revocation tracking fields
  • C3.4: Added DDL reference section (Section 13) pointing to resources/SCHEMA_walking_skeleton_v4_2.sql
  • C3.5: Standardized lifecycle consistency — added explicit Human Decision lifecycle note (Section 5.5.6) clarifying it is a Durable Record without full workflow lifecycle. Added Escalation Request status and status_state fields to entity definition.
  • C3.6: Added 4-digit ticket numbering scheme (Section 2.7) — new tickets start at 1001, sub-tasks use dot notation, historical 3-digit tickets preserved
  • CX.1: Global naming fix — "Rufio" replaced with "Ruflo" (no instances in Part 3)
  • CX.2: Version header updated to 4.2.0, last_updated to 2026-03-28
  • CX.3: Added this changelog section
  • CX.4: Added Current State section (Section 17) documenting existing ODM state
  • Renumbered sections 13-17 to 14-19 to accommodate DDL reference insertion
  • Added Core Entity List table (Section 3.1) for quick reference across all entities

v5.0.1 (2026-03-28)

Unified Agent Identity Model:

  • Section 4.7 (Agent Template): Updated schema to use 3-digit agent_id, roles array (from role_bundles), is_master flag, and default LLM/Auth binding fields. Replaced layer enum with roles array. Replaced code with agent_id.
  • Section 4.8 (Agent Runtime): Updated schema to use 3-digit agent_id, orchestrator_id, and full LLM/Auth Binding (auth_method, auth_account, api_key_ref, litellm_model_id). Replaced runtime_kind values from O/B/W/system to orchestrator/specialist/worker/interface/system. Renamed host_node_id to host_id. Replaced owner_orchestrator_id with orchestrator_id.
  • Updated all O00/O01 references to "000 (orchestrator role)" / "000 (governor role)" throughout
  • Updated Topic Enrichment Layer responsibilities table to use role-based naming

v5.0.2 (2026-03-28)

Agent naming migration verification: Part 3 was already migrated in v5.0.1. No additional changes required. Changelog entry added for completeness.

v5.0.3 (2026-03-28)

Idea + User entities:

  • Section 3: Updated Core Entities mermaid diagram to include User and Idea nodes with bidirectional Idea-DiscussionThread links
  • Section 3.1: Added User (4.0) and Idea (4.3B) to Core Entity List table
  • Section 4.0: Added User entity definition — first-class identity/access entity with role enum (founder | operator | reviewer | observer), auth_accounts, is_primary flag, notification_channels, and status
  • Section 4.3A: Added idea_ids: [string] to DiscussionThread properties for many-to-many Idea link. Added note about Idea-Discussion bidirectional relationship.
  • Section 4.3B: Added Idea entity definition — lifecycle-bearing entity with source enum, review_cycle, discussion_thread_ids, ticket_id link, priority, and tags. Includes Idea lifecycle mermaid diagram and Idea-Discussion-Ticket flow section with mermaid flow.
  • Section 4.3A: Updated "founder guidance" to "user guidance" in DiscussionThread purpose
  • Section 5.5.9: Added Idea Lifecycle with custom status set (new | under_discussion | approved | ticketed | deferred | rejected | archived) and typical flow mermaid diagram
  • Renumbered Research Task Lifecycle from 5.5.9 to 5.5.10

v5.0.4 (2026-03-28)

Roles over numbers: Removed agent IDs from architectural descriptions, responsibility tables, and diagrams. Agent numbers retained only in ODM entity schemas (agent_template, agent_runtime). Role names used throughout instead of agent numbers.

v5.0.5 (2026-03-29)

User ToDo / Attention Queue entity:

  • Section 4.14: Added User ToDo (Attention Queue Item) entity definition with full property schema, auto-generation contract (6 trigger types), auto-dismiss contract (3 condition types), and dedup key specification (linked_type + linked_id). Classified as Durable Decision / Record Object.

v5.0.6 (2026-03-30)

Round 2 review fix (dual-DB architecture):

  • Section 19: Added Dual-Database Architecture section documenting the bus and devxio databases, rationale for separation (Bus is standalone MCP service), cross-database relationship (agent_registry.id maps to agent_runtimes.agent_id), migration ownership (Bus manages its own; walking skeleton manages devxio via Alembic), and operational rules (no cross-DB joins, no cross-DB foreign keys).
  • Renumbered former Section 19 (Final Statement) to Section 20.

v5.0.7 (2026-03-30)

I5 review fix:

  • Section 4.6.4: Added Activity Table Partitioning Strategy -- monthly range partitioning on created_at, automated partition creation via pg_cron or Governor, 6-month hot storage with cold archive to Backblaze B2, per-partition indexes on (agent_id, created_at) and (task_id, created_at). Same strategy applies to cost_ledger and time_ledger if they exceed 1M rows.

v5.0.8 (2026-03-30)

N5 review fix (spec versioning):

  • Section 4.5 (Task): Added spec_version: int (default 1, increments when task description changes) and spec_snapshot: jsonb|null (captures task spec at assignment time). Added notes explaining spec drift prevention and snapshot update rules.