Data model

Schema · Venues, routing & cost

The Part V operational tables — venues and capabilities, execution quotes and trade costs, AI/API usage, budgets, the model registry, benchmarks and routing logs.

These tables extend the Convex operational model with the venue, routing and cost-governance state introduced in Part V. They hold current state and recent decisions — bulk history still lives in Parquet/DuckDB.

Venues & capabilities

venues

Field	Type	Description
`id`	ID	Venue ID
`type`	string	cex, dex, aggregator, launchpad
`ccxt_exchange_id`	string, optional	CCXT exchange ID where applicable
`chain_id`	string, optional	Chain for on-chain venues
`name`	string	Human-readable name
`trust_tier`	integer	0 discovery → 5 fully approved
`enabled_for_discovery`	boolean	Surfaced to the discovery engine
`enabled_for_execution`	boolean	Allowed to receive orders
`human_approval_required`	boolean	Orders need a human gate
`status`	string	Active, degraded, disabled
`last_health_check_at`	datetime	Last connectivity/health check

venue_capabilities

Field	Type	Description
`venue_id`	string	Owning venue
`capability`	string	e.g. fetchOHLCV, createOrder, watchOrderBook
`supported`	boolean	Verified support (not just CCXT has.*)
`implementation`	string	ccxt, native, aggregator, manual
`tested_version`	string	CCXT / adapter version contract-tested
`last_verified_at`	datetime	Last regression verification
`notes`	string, optional	Venue-specific caveats

Routing & trade cost

execution_quotes

Field	Type	Description
`id`	ID	Quote ID
`trade_candidate_id`	string	Candidate being priced
`venue_id`	string	Quoting venue
`route`	object	Pools / path / aggregator route
`input_amount`	number	Quoted input amount
`expected_output_amount`	number	Quoted output amount
`expected_fee_usd`	number	Trading/provider fee estimate
`expected_gas_usd`	number	Gas + priority fee estimate
`expected_slippage_percent`	number	Estimated slippage
`expected_price_impact_percent`	number	Estimated price impact
`provider_fee_usd`	number	Aggregator/affiliate fee
`expires_at`	datetime	Quote expiry

trade_costs

Field	Type	Description
`order_id`	string	Owning order
`exchange_fee_usd`	number	Maker/taker fee realized
`gas_fee_usd`	number	Network gas
`priority_fee_usd`	number	Priority fee / validator tip
`spread_cost_usd`	number	Spread cost
`slippage_cost_usd`	number	Realized slippage
`price_impact_cost_usd`	number	Realized price impact
`provider_fee_usd`	number	Aggregator/provider fee
`withdrawal_fee_usd`	number	Withdrawal fee
`bridge_fee_usd`	number	Bridge fee
`failed_transaction_cost_usd`	number	Gas burned on failed tx
`total_cost_usd`	number	Sum of all cost components

Usage & budgets

ai_usage_logs

Field	Type	Description
`provider`	string	Model provider
`model`	string	Model id
`agent`	string	Calling agent
`workflow`	string	Workflow / graph node
`strategy_id`	string, optional	Related strategy
`trade_candidate_id`	string, optional	Related candidate
`input_tokens`	integer	Prompt tokens
`cached_input_tokens`	integer	Cached prompt tokens
`output_tokens`	integer	Completion tokens
`reasoning_tokens`	integer, optional	Reasoning tokens where reported
`tool_calls`	integer	Tool calls made
`estimated_cost_usd`	number	Estimated call cost
`latency_ms`	integer	Round-trip latency
`success`	boolean	Validated output
`created_at`	datetime	Call time

external_api_usage_logs

Field	Type	Description
`provider`	string	Data/RPC/social provider
`endpoint`	string	Endpoint called
`workflow`	string	Calling workflow
`resource_type`	string	compute_units, requests, etc.
`request_count`	integer	Requests in this entry
`units_consumed`	number	Provider units consumed
`estimated_cost_usd`	number	Estimated cost
`status_code`	integer, optional	HTTP status
`latency_ms`	integer	Round-trip latency
`created_at`	datetime	Call time

usage_budgets

Field	Type	Description
`scope_type`	string	provider, model, agent, strategy, candidate
`scope_id`	string	Scoped entity ID
`daily_limit_usd`	number	Daily cap
`monthly_limit_usd`	number	Monthly cap
`warning_threshold_percent`	number	Warn at this %
`hard_stop_enabled`	boolean	Block paid calls at 100%
`fallback_provider`	string, optional	Fallback provider
`fallback_model`	string, optional	Fallback model
`enabled`	boolean	Budget active

shared_infrastructure_allocations

Field	Type	Description
`id`	ID	Allocation ID
`resource_type`	string	vps, domain, backup, gpu
`resource_name`	string	Resource identifier
`period`	string	Accounting period
`total_resource_cost_usd`	number	Total cost of the shared resource
`allocation_method`	string	usage_share, fixed, weighted
`clawlas_allocation_percent`	number	Clawlas's share %
`allocated_cost_usd`	number	Allocated economic cost
`cpu_usage_share`	number, optional	CPU share
`memory_usage_share`	number, optional	Memory share
`disk_usage_share`	number, optional	Disk share
`network_usage_share`	number, optional	Network share
`created_at`	datetime	Record time

Model registry & routing

model_registry

Field	Type	Description
`id`	ID	Registry ID
`provider`	string	Provider
`model_id`	string	Model identifier
`model_version`	string	Pinned version
`hosting_type`	string	cloud_api, local_cpu, local_gpu, remote_gpu
`endpoint`	string, optional	Serving endpoint
`supported_tasks`	string[]	Tasks this model is eligible for
`supports_tools`	boolean	Tool calling
`supports_structured_output`	boolean	Reliable schema output
`context_window`	integer	Max context tokens
`input_price_per_million`	number, optional	Input price
`cached_input_price_per_million`	number, optional	Cached input price
`output_price_per_million`	number, optional	Output price
`estimated_local_cost_per_hour`	number, optional	Local serving cost/hour
`privacy_class`	string	Privacy tier
`fallback_group`	string, optional	Fallback group
`enabled`	boolean	Available to the router
`created_at`	datetime	Creation date
`updated_at`	datetime	Last update

model_task_benchmarks

Field	Type	Description
`id`	ID	Benchmark ID
`model_registry_id`	string	Benchmarked model
`task_type`	string	Task evaluated
`benchmark_version`	string	Golden-dataset version
`sample_count`	integer	Samples evaluated
`quality_score`	number	Task-specific quality
`schema_success_rate`	number	Valid-schema rate
`false_positive_rate`	number, optional	FP rate
`false_negative_rate`	number, optional	FN rate
`p50_latency_ms`	integer	Median latency
`p95_latency_ms`	integer	Tail latency
`cost_per_valid_result_usd`	number	Cost per valid result
`evaluated_at`	datetime	Evaluation time

model_routing_logs

Field	Type	Description
`id`	ID	Routing decision ID
`workflow`	string	Calling workflow
`task_type`	string	Task routed
`risk_level`	string	Task risk level
`expected_value_usd`	number, optional	Expected value of the task
`candidate_models`	array	Considered candidates
`selected_model_registry_id`	string, optional	Chosen model
`selected_route_type`	string	deterministic, cache, local, cloud, premium, human
`selection_reason`	object	Why this route won
`estimated_cost_usd`	number	Pre-call estimate
`actual_cost_usd`	number	Realized cost
`latency_ms`	integer	Latency
`validation_passed`	boolean	Output validated
`fallback_used`	boolean	Fallback triggered
`escalation_count`	integer	Escalations taken
`created_at`	datetime	Decision time

Identity & trust

A venue is keyed by its CCXT id or chain, carries a trust tier 0–5, and gates execution; venue_capabilities records what was actually verified (not just what CCXT has.* reports) and the version it was tested against.

Field lists are conceptual — Convex v.* validators and the shared Zod schemas are the source of truth in code.