Skip to content

Generated file

This page is generated from hadron-server/prisma/schema.prisma. To refresh it, run npm run docs:entities from the root of this repo.

Code paths below are not local. The descriptions come from doc comments written inside hadron-server, so a path like src/lib/tokenCrypto.ts or prisma/post-push.sql is relative to the hadron-server repository — there is no such file here. They point at the implementation and are volatile; the durable statement is the description itself.

Hadron Data Model

Generated by prisma-markdown

default

erDiagram
"users" {
  String id PK
  String handle UK
  Json policy "nullable"
  Int github_id UK "nullable"
  String github_username UK "nullable"
  String google_id UK "nullable"
  String apple_id UK "nullable"
  IdentityProvider identity_provider "nullable"
  String external_id "nullable"
  String external_app_id FK "nullable"
  DateTime linked_at "nullable"
  String name "nullable"
  String email UK "nullable"
  String avatar_url "nullable"
  Role roles
  Int max_referrals "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  String principal_id FK,UK "nullable"
}
"user_merges" {
  String source_user_id PK,FK
  String target_user_id FK
  DateTime merged_at
  String merged_by "nullable"
  String consent_hash UK "nullable"
  Json consent_receipt "nullable"
}
"user_merge_consents" {
  String id PK
  String proof_hash UK
  String source_user_id
  String target_user_id
  String requested_by
  String scope
  DateTime created_at
  DateTime expires_at
  DateTime source_login_at "nullable"
  String source_login_method "nullable"
  DateTime target_login_at "nullable"
  String target_login_method "nullable"
  DateTime consumed_at "nullable"
}
"dashboard_widgets" {
  String id PK
  String user_id FK
  DashboardWidgetType type
  Int span
  Int row_span
  Json config "nullable"
  Int position
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
}
"dashboard_widget_presets" {
  String id PK
  String user_id FK
  DashboardWidgetType type
  String name
  Json config
  DateTime created_at
  DateTime updated_at
}
"organizations" {
  String id PK
  String name
  String urn UK
  Boolean listed_on_marketplace
  Int github_installation_id UK "nullable"
  String github_app_id "nullable"
  String github_app_private_key_encrypted "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  Json policy "nullable"
  String principal_id FK,UK "nullable"
}
"principals" {
  String id PK
  String name UK
  String kind
  String status
  DateTime released_at "nullable"
  DateTime created_at
  DateTime updated_at
}
"org_members" {
  String id PK
  String organization_id FK
  String user_id FK
  Role role
  Boolean can_invite
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"memories" {
  String id PK
  String organization_id FK "nullable"
  String owner_user_id FK "nullable"
  String app_id FK "nullable"
  String user_id FK "nullable"
  String user_memory_of_agent_id FK "nullable"
  String shared_memory_of_agent_id FK "nullable"
  String install_of_agent_id FK "nullable"
  Boolean is_install_memory
  String urn UK
  String name
  String short_description "nullable"
  String description "nullable"
  Json data "nullable"
  Json schema "nullable"
  Boolean corpus_draft
  DateTime corpus_minted_at "nullable"
  String corpus_minted_by "nullable"
  String tags
  String license "nullable"
  String category_0 "nullable"
  String category_1 "nullable"
  String category_2 "nullable"
  String icon_url "nullable"
  String hero_url "nullable"
  String home_url "nullable"
  String source "nullable"
  String source_token_encrypted "nullable"
  DateTime source_token_expires_at "nullable"
  String read_branch "nullable"
  Boolean read_branch_corrected
  String write_branch "nullable"
  MemoryVisibility visibility "nullable"
  Boolean listed_on_marketplace
  Boolean is_encrypted
  MemoryClass class
  DateTime anonymous_expires_at "nullable"
  Boolean requires_license
  DateTime last_synced_at "nullable"
  SyncStatus sync_status
  String sync_error "nullable"
  String last_sync_report "nullable"
  Int pending_edge_count
  Boolean accepts_uploads
  Boolean vector_index_enabled
  EmbeddingSource embedding_source
  Int chunk_tokens "nullable"
  Int chunk_overlap "nullable"
  Boolean force_fixed_size
  Int max_rev_count
  String kdf_salt "nullable"
  Json kdf_params "nullable"
  String key_verifier "nullable"
  DateTime vector_index_encrypted_ack_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  DateTime urn_normalized_at "nullable"
  String urn_migration_failed_reason "nullable"
  String legacy_urn "nullable"
}
"assets" {
  String id PK
  String memory_id FK "nullable"
  String filename
  String mime_type
  Int size_bytes
  String storage_key UK
  AssetScanStatus scan_status
  String scan_signature "nullable"
  Int scan_attempts
  DateTime scanned_at "nullable"
  DateTime scan_due_at "nullable"
  DateTime bytes_checked_at "nullable"
  String description "nullable"
  DateTime uploaded_at
  String uploaded_by "nullable"
  DateTime deleted_at "nullable"
  Boolean public_link_enabled
}
"nodes" {
  String id PK
  String memory_id FK
  String node_type
  String object_type "nullable"
  String name
  String alias "nullable"
  String loc
  Boolean is_link
  Boolean is_placeholder
  String description "nullable"
  String abstract "nullable"
  String content "nullable"
  String content_hash "nullable"
  String abstract_origin_hash "nullable"
  DateTime embedding_pending_at "nullable"
  String embedding_work_token "nullable"
  DateTime embedding_failed_at "nullable"
  Int embedding_attempts
  Int embedding_truncated_chunks "nullable"
  String embedding_error "nullable"
  Int tokens "nullable"
  String tags
  Json properties "nullable"
  Json data "nullable"
  Int seq "nullable"
  String message_channel_id "nullable"
  String owner_repo "nullable"
  Boolean is_runnable "nullable"
  String role "nullable"
  String llm_model "nullable"
  String ai_agent "nullable"
  NodeAuthorshipKind authorship_kind "nullable"
  String authored_by_task "nullable"
  Int authored_by_revision "nullable"
  String authored_by_human "nullable"
  DateTime authored_at "nullable"
  Int rev_seq
  Int content_rev_seq
  String revision_content_hash "nullable"
  Int approved_rev_no "nullable"
  String approved_by "nullable"
  String approved_by_info "nullable"
  DateTime approved_at "nullable"
  String approval_hash "nullable"
  DateTime minted_at "nullable"
  String minted_by "nullable"
  String minted_by_info "nullable"
  Int minted_rev_no "nullable"
  String minted_hash "nullable"
  DateTime content_changed_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  String created_by_worker_id "nullable"
  String created_by_agent_id "nullable"
  String updated_by_worker_id "nullable"
  String updated_by_agent_id "nullable"
  String updated_by_user_id "nullable"
}
"node_embeddings" {
  String id PK
  String node_id FK
  String memory_id FK
  EmbeddingKind kind
  String provider
  String model
  Int dim
  Int chunk_index "nullable"
  Int char_start "nullable"
  Int char_end "nullable"
  String chunk_text "nullable"
  DateTime created_at
}
"edges" {
  String id PK
  String memory_id FK
  String source_id FK
  String target_id FK
  String loc
  String name "nullable"
  String description "nullable"
  Boolean is_runnable "nullable"
  Json condition "nullable"
  Int priority
  Json data "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  EdgeGovernedKind governed_kind "nullable"
  Int anchor_rev_no "nullable"
  String anchor_approval_hash "nullable"
}
"comment_meta" {
  String node_id PK,FK
  String target_node_id FK
  String thread_root_id "nullable"
  CommentThreadState thread_state "nullable"
  String author_key
  DateTime retracted_at "nullable"
  String retracted_by "nullable"
  DateTime resolved_at "nullable"
  String resolved_by "nullable"
  DateTime thread_deleted_at "nullable"
  String thread_deleted_by "nullable"
  String thread_deleted_cause "nullable"
  DateTime created_at
}
"pending_edges" {
  String id PK
  String source_id FK
  String target_id
  String loc "nullable"
  String name "nullable"
  String description "nullable"
  Json data "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"sessions" {
  String id PK
  SessionType type
  String app_id FK "nullable"
  String user_id FK "nullable"
  String agent_id FK "nullable"
  String worker_id FK "nullable"
  String role "nullable"
  String memory_id FK "nullable"
  DateTime expires_at "nullable"
  String repo "nullable"
  String branch "nullable"
  Int pr_number "nullable"
  String customer_id "nullable"
  String language "nullable"
  String plan "nullable"
  String llm_model "nullable"
  String transcript_path "nullable"
  String host "nullable"
  String tool "nullable"
  String family "nullable"
  DateTime model_reported_at "nullable"
  String launch_host_id "nullable"
  String launch_operation_id UK "nullable"
  String launch_task_id "nullable"
  String launch_issued_by "nullable"
  Int input_tokens "nullable"
  Int output_tokens "nullable"
  Int turn_count "nullable"
  Int error_count "nullable"
  String parent_session_id FK "nullable"
  String prev_session_id FK "nullable"
  String summary "nullable"
  Float outcome "nullable"
  String outcome_ref "nullable"
  Json outcome_meta "nullable"
  DateTime started_at
  DateTime ended_at "nullable"
  SessionEndReason end_reason "nullable"
  DateTime auto_expired_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"usage_events" {
  String id PK
  String type
  String node_loc "nullable"
  String node_id FK "nullable"
  String memory_id "nullable"
  String session_id FK "nullable"
  String app_id FK "nullable"
  Json action_args "nullable"
  String model "nullable"
  Int tokens_in "nullable"
  Int tokens_out "nullable"
  String user_id FK "nullable"
  String organization_id FK "nullable"
  String provider "nullable"
  String key_owner_type "nullable"
  BigInt cost_micro_cents "nullable"
  Boolean counts_as_activity
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"agents" {
  String id PK
  Boolean uses_tasks
  Boolean reset_context_after_task
  String organization_id FK "nullable"
  String owner_user_id FK "nullable"
  String urn UK
  String name
  String description "nullable"
  String boot_prompt_node_id "nullable"
  String boot_prompt_urn "nullable"
  String system_memory_id "nullable"
  AgentVisibility visibility
  Boolean listed_on_marketplace
  AgentType type
  String surfaces
  String published_revision_loc "nullable"
  String editor_lock_user_id "nullable"
  DateTime editor_lock_expires_at "nullable"
  Json properties "nullable"
  Json memory_provisioning
  Json register_defaults "nullable"
  Json installation_policy
  String persona_role "nullable"
  String extends_agent_id FK "nullable"
  String cloned_from_agent_ref "nullable"
  String tasks_index_ref FK "nullable"
  String processes_index_ref FK "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  DateTime urn_normalized_at "nullable"
  String urn_migration_failed_reason "nullable"
  String legacy_urn "nullable"
}
"agent_memory_items" {
  String id PK
  String agent_id FK
  String memory_id FK
  String role
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"memory_licenses" {
  String id PK
  String memory_id FK
  String license_type
  Int seats
  DateTime valid_from
  DateTime valid_until
  String license_keys
  String terms
  Boolean activated
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"memory_subscriptions" {
  String id PK
  String memory_id FK
  String organization_id FK
  String license_id FK "nullable"
  Role role
  Boolean activated
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"hadron_server" {
  String id PK
  String organization_id "nullable"
  String url
  LogLevel log_level
  String version "nullable"
  DateTime last_heartbeat_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"ai_service_configs" {
  String id PK
  String name
  String hadron_server_id FK "nullable"
  String organization_id FK "nullable"
  String app_id FK "nullable"
  String agent_id FK "nullable"
  String provider
  String model
  String api_key_encrypted "nullable"
  String api_key_preview "nullable"
  Json params "nullable"
  String endpoint "nullable"
  String api_style "nullable"
  Boolean enabled
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"server_log" {
  String id PK
  String server_id FK
  LogLevel level
  String memory_id "nullable"
  String message
  Json detail "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"memory_log" {
  String id PK
  String memory_id FK
  LogLevel level
  MemoryLogEventType event_type
  String message
  Json detail "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"org_member_invitations" {
  String id PK
  String member_user_id FK
  String recipient_user_id FK
  Role role
  DateTime expires_at "nullable"
  DateTime accepted_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"user_invitations" {
  String id PK
  String sender_user_id FK "nullable"
  String organization_id FK "nullable"
  String slug UK
  Role user_role "nullable"
  Role member_role
  String new_user_id "nullable"
  String name "nullable"
  String email "nullable"
  String github_username "nullable"
  String phone_number "nullable"
  Int max_activations "nullable"
  DateTime expires_at "nullable"
  DateTime accepted_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"user_invitation_activations" {
  String id PK
  String invitation_id FK
  String user_id FK
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"email_verification_tokens" {
  String id PK
  String email
  String token UK
  DateTime expires_at
  DateTime used_at "nullable"
  DateTime created_at
  String client_state_hash "nullable"
}
"compiled_prompt_revisions" {
  String compiled_node_id FK
  Int compiled_rev_no
  String content_hash
  String target_kind
  String target_agent_id
  String target_app_id "nullable"
  String target_worker_id "nullable"
  Json provenance
  Int occurrence_count
  String compiled_by "nullable"
  DateTime created_at
}
"node_revisions" {
  String id PK
  String node_id FK
  String memory_id "nullable"
  String loc
  String name
  String alias "nullable"
  String description "nullable"
  String abstract "nullable"
  String abstract_origin_hash "nullable"
  String content "nullable"
  String tags
  String node_type "nullable"
  String object_type "nullable"
  Boolean is_link "nullable"
  Json properties "nullable"
  Json data "nullable"
  Int seq "nullable"
  Boolean is_runnable "nullable"
  String role "nullable"
  String llm_model "nullable"
  String ai_agent "nullable"
  NodeAuthorshipKind authorship_kind "nullable"
  String authored_by_task "nullable"
  Int authored_by_revision "nullable"
  String authored_by_human "nullable"
  DateTime authored_at "nullable"
  String edited_by "nullable"
  String edited_by_info "nullable"
  String edited_by_worker_id "nullable"
  String edited_by_agent_id "nullable"
  String rev_label "nullable"
  String changes
  String approved_by FK "nullable"
  String approved_by_info "nullable"
  DateTime approved_at "nullable"
  String approval_hash "nullable"
  Int rev_no "nullable"
  String created_by "nullable"
  DateTime created_at
}
"node_content_validation_reports" {
  String id PK
  String node_id FK
  String memory_id
  Int node_rev_seq
  String validation_task_id
  Int validation_task_rev_seq
  NodeContentValidationOutcome outcome
  DateTime reported_at
  String run_id UK "nullable"
}
"pending_setups" {
  String id PK
  String user_id FK,UK
  String app_id FK
  String raw_key_encrypted
  Boolean consumed
  String created_by "nullable"
  DateTime created_at
}
"exchange_connections" {
  String id PK
  String organization_id FK
  String user_id FK
  String mailbox_email
  String display_name "nullable"
  String provider
  String tool_connection_id "nullable"
  String refresh_token_encrypted "nullable"
  Boolean sync_enabled
  SyncStatus sync_status
  DateTime last_sync_at "nullable"
  String last_error "nullable"
  String webhook_subscription_id "nullable"
  DateTime webhook_expires_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"connection_flows" {
  String id PK
  String user_id FK
  String organization_id FK
  String provider
  DateTime started_at
  String connection_id "nullable"
  String failure_code "nullable"
  DateTime settled_at "nullable"
}
"connection_grants" {
  String id PK
  String connection_id FK
  String grantee_app_id FK
  String granted_by_user_id FK
  String scopes
  DateTime expires_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"principal_grants" {
  String id PK
  String principal_type
  String principal_id FK
  String organization_id FK
  String actions
  DateTime expires_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"slack_connections" {
  String id PK
  String organization_id FK
  String default_app_id FK
  String provider
  String tool_connection_id UK
  String team_id
  String team_name
  String bot_user_id
  String bot_id
  String status
  String last_error "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"slack_event_receipts" {
  String id PK
  String connection_id
  String envelope_id
  DateTime created_at
}
"webfetch_poll_bindings" {
  String job_id PK
  String source_run_id FK
  String organization_id
  String app_id
  String agent_id "nullable"
  String user_id "nullable"
  String entry_node_urn
  Json policy "nullable"
  String credential_secret_id "nullable"
  String url
  DateTime cancelled_at "nullable"
  DateTime created_at
}
"webfetch_event_receipts" {
  String id PK
  String job_id
  String snapshot_hash
  String kind
  String routed_run_id FK
  DateTime created_at
}
"mcp_servers" {
  String id PK
  String organization_id FK
  String slug
  String name
  String url
  String headers_encrypted "nullable"
  String tool_allowlist
  Boolean enabled
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
}
"secrets" {
  String id PK
  String owner_type
  String owner_id
  String name
  String kind
  Json metadata
  String value_encrypted
  String key_id "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
}
"home_assistant_instances" {
  String id PK
  String organization_id FK
  String slug
  String name
  String url
  String token_encrypted
  String op_allowlist
  Boolean enabled
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
}
"resend_senders" {
  String id PK
  String organization_id FK,UK
  String from_address
  String api_key_encrypted
  Boolean enabled
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
}
"waiting_list" {
  String id PK
  String email
  String requested_features "nullable"
  DateTime created_at
}
"apps" {
  String id PK
  String name
  Json policy "nullable"
  String urn
  String organization_id FK "nullable"
  String owner_user_id FK "nullable"
  CreateUserPermission create_user_permission
  IdentifyUserMethod identify_user_method
  Int session_timeout_seconds
  Int session_dormancy_days
  Boolean agent_sessions_expire
  Int anonymous_ttl_days
  Int ticker_min_cadence_seconds
  Int delivery_busy_delay_seconds
  Int delivery_stuck_window_seconds
  Boolean delivery_standby_enabled
  Int delivery_check_period_seconds
  Int delivery_failed_checks_to_overdue
  Int delivery_dark_alarm_window_seconds
  DateTime team_paused_at "nullable"
  DateTime team_resumed_at "nullable"
  Int ticker_self_subscribe_cadence_seconds
  Int ticker_live_cap
  Int wake_daily_budget "nullable"
  Json properties "nullable"
  Int properties_revision
  Boolean run_team_snapshot_enabled
  AppType app_type
  AppMembershipRole role
  String description "nullable"
  String agent_tools
  DateTime expires_at "nullable"
  Boolean training_mode
  String surfaces
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  DateTime uninstalled_at "nullable"
  DateTime urn_normalized_at "nullable"
  String urn_migration_failed_reason "nullable"
  String legacy_urn "nullable"
  String default_channel_id FK,UK "nullable"
}
"app_keys" {
  String id PK
  String app_id FK
  String key_hash UK
  String key_preview
  String label "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime last_used_at "nullable"
  DateTime revoked_at "nullable"
}
"app_members" {
  String app_id FK
  String user_id FK
  String role
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"agent_org_grants" {
  String org_id FK
  String agent_id FK
  DateTime activated_at "nullable"
  DateTime expires_at "nullable"
  DateTime revoked_at "nullable"
  String revoked_by "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"agent_imports" {
  String parent_agent_id FK
  String imported_agent_id FK
  Int position
  Boolean required
  String agent_org_grant_org_id FK
  String agent_org_grant_agent_id
  DateTime created_at
  String created_by "nullable"
}
"agent_subscriptions" {
  String user_id FK
  String agent_id FK
  DateTime activated_at "nullable"
  DateTime expires_at "nullable"
  DateTime revoked_at "nullable"
  String revoked_by "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"app_log" {
  String id PK
  String app_id FK
  LogLevel level
  String memory_id "nullable"
  String session_id "nullable"
  String message
  Json detail "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"app_agents" {
  String app_id FK
  String agent_id FK
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  String boot_prompt_node_id "nullable"
  String boot_prompt_urn "nullable"
}
"workers" {
  String id PK
  String app_id FK
  String agent_id FK
  String name
  String slug
  String role "nullable"
  String signature
  String trailer
  String boot_prompt_node_id "nullable"
  String boot_prompt_urn "nullable"
  String memory_id FK "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  String held_by_user_id FK "nullable"
  DateTime held_at "nullable"
  DateTime retired_at "nullable"
  String retired_by "nullable"
  String reports_to_worker_id FK "nullable"
  Boolean explicit_no_team
  Json terminal "nullable"
}
"memory_shares" {
  String memory_id FK
  String grantee_id FK
  String grantor_id FK
  MemoryShareRole role
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"memory_members" {
  String memory_id FK
  String user_id FK
  MemoryMemberRole role
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"user_api_keys" {
  String id PK
  String user_id FK
  String key_hash UK
  String key_preview
  String label "nullable"
  DateTime created_at
  String created_by "nullable"
  String issued_via "nullable"
  String oauth_scopes
  DateTime last_used_at "nullable"
  DateTime revoked_at "nullable"
  DateTime hidden_at "nullable"
  String minted_by_key_id FK "nullable"
  String origin_sign_in_id FK "nullable"
}
"impersonation_sessions" {
  String id PK
  String admin_user_id FK
  String target_user_id FK
  String organization_id FK
  String reason "nullable"
  DateTime created_at
  DateTime expires_at
  DateTime ended_at "nullable"
  String ended_by "nullable"
}
"oauth_clients" {
  String client_id PK
  String client_name
  String redirect_uris
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  DateTime expires_at "nullable"
}
"auth_codes" {
  String id PK
  String code_hash UK
  String client_id FK
  String user_id FK
  String redirect_uri
  String code_challenge
  String resource
  String oauth_scopes
  DateTime expires_at
  DateTime redeemed_at "nullable"
  DateTime created_at
  String created_by "nullable"
  String sign_in_id FK "nullable"
}
"passkey_ceremonies" {
  String id PK
  String purpose
  String browser_nonce_hash
  String challenge_hash
  DateTime created_at
  DateTime expires_at
  DateTime consumed_at "nullable"
  String user_id FK "nullable"
  String kind "nullable"
  String registration_method "nullable"
  String sign_in_browser_hash "nullable"
  String vouch_passkey_id FK "nullable"
  Bytes user_handle "nullable"
}
"passkey_registration_notices" {
  String id PK
  String passkey_id FK,UK
  String user_id FK
  String kind
  String cancel_token_enc "nullable"
  DateTime created_at
  Int attempts
  DateTime lease_until "nullable"
  String claim_token "nullable"
  DateTime sent_at "nullable"
  DateTime failed_at "nullable"
  DateTime seen_at "nullable"
}
"passkey_cancel_tokens" {
  String id PK
  String passkey_id FK,UK
  String token_hash UK
  DateTime created_at
  DateTime used_at "nullable"
}
"fresh_sign_ins" {
  String id PK
  String user_id FK
  String method
  String browser_nonce_hash
  String leg_hash UK
  DateTime created_at
  DateTime expires_at
  DateTime signed_in_at "nullable"
  DateTime confirmed_at "nullable"
  DateTime consumed_at "nullable"
  String consumed_for "nullable"
}
"pending_email_sign_ins" {
  String id PK
  String user_id FK
  String continuation
  String client_state_hash "nullable"
  String redirect "nullable"
  Boolean is_new "nullable"
  String return_to "nullable"
  String browser_hash UK
  String ceremony_id "nullable"
  DateTime created_at
  DateTime expires_at
  DateTime completed_at "nullable"
  String sign_in_id FK "nullable"
}
"passkey_credentials" {
  String id PK
  String owner_id FK
  Bytes credential_id UK
  Bytes public_key
  Int algorithm
  Bytes user_handle
  String enrollment_rp_id
  String label
  DateTime registered_at
  DateTime last_used_at "nullable"
  DateTime revoked_at "nullable"
  BigInt counter
  String transports
  Boolean backup_eligible
  Boolean backed_up
  String registration_method "nullable"
  DateTime window_ends_at "nullable"
  DateTime window_ended_at "nullable"
  String window_outcome "nullable"
  DateTime cancelled_at "nullable"
  String cancel_ip "nullable"
  String cancel_user_agent "nullable"
}
"user_api_key_deletions" {
  String id PK
  String user_id FK
  String key_id
  String key_preview
  String revoked_key_ids
  String minted_key_ids
  DateTime deleted_at
}
"sign_ins" {
  String id PK
  String user_id FK
  String method
  String completed_by_passkey_id FK "nullable"
  DateTime completed_at
  DateTime expires_at
  DateTime ended_at "nullable"
  String end_reason "nullable"
}
"signing_requests" {
  String id PK
  String node_id FK
  Int revision
  String approval_hash
  String payload_version
  String named_signer_id "nullable"
  String requester_user_id "nullable"
  String requester_app_id "nullable"
  String requester_worker_id "nullable"
  String requester_session_id "nullable"
  String state
  DateTime created_at
  DateTime expires_at
  DateTime ended_at "nullable"
}
"node_signatures" {
  String id PK
  String node_id FK
  String signing_request_id FK,UK
  String signer_id
  String passkey_credential_id FK
  Int revision
  String approval_hash
  String payload_version
  String rp_id
  Bytes authenticator_data
  Bytes client_data_json
  Bytes signature
  DateTime verified_at
}
"auth_handoff_codes" {
  String id PK
  String code_hash UK
  String kind
  String user_id FK
  String redirect "nullable"
  Boolean is_new
  Json login_evidence "nullable"
  String org_id "nullable"
  String client_state_hash "nullable"
  DateTime expires_at
  DateTime redeemed_at "nullable"
  DateTime created_at
  String sign_in_id FK "nullable"
  String flow_id "nullable"
}
"pending_login_states" {
  String state PK
  String provider
  String redirect "nullable"
  String return_to "nullable"
  String client_state "nullable"
  String ceremony_nonce_hash "nullable"
  String provider_nonce_hash "nullable"
  DateTime expires_at
  DateTime created_at
}
"app_runs" {
  String id PK
  String organization_id
  String app_id
  String agent_id "nullable"
  String user_id "nullable"
  AppRunTriggerKind trigger_kind
  String trigger_id "nullable"
  Json automation_pin "nullable"
  String entry_node_urn
  String entry_node_id "nullable"
  Json event_data "nullable"
  Json data "nullable"
  Json hops "nullable"
  Json derived_log "nullable"
  Json spawn "nullable"
  Json policy "nullable"
  Int budget_tokens "nullable"
  Int budget_actions "nullable"
  Int budget_tokens_initial "nullable"
  Int budget_actions_initial "nullable"
  Int tokens_spent "nullable"
  Int actions_spent "nullable"
  BigInt cost_micro_cents "nullable"
  AppRunStatus status
  String cur_node_urn "nullable"
  Json scope_snapshot "nullable"
  Json register_snapshot "nullable"
  String parent_run_id "nullable"
  Json failure "nullable"
  Int timeout_ms "nullable"
  Int attempts
  DateTime published_at "nullable"
  DateTime started_at "nullable"
  DateTime finished_at "nullable"
  DateTime created_at
  String created_by "nullable"
}
"agent_schedules" {
  String id PK
  String organization_id
  String app_id
  String agent_id "nullable"
  String user_id "nullable"
  String name
  String cron "nullable"
  String timezone
  DateTime run_at "nullable"
  Json automation_pin "nullable"
  String entry_node_urn
  String entry_node_id "nullable"
  Int budget_tokens "nullable"
  Int budget_actions "nullable"
  Json event_data "nullable"
  Json policy "nullable"
  String ai_config_name "nullable"
  String scope_id FK "nullable"
  Boolean enabled
  DateTime last_run_at "nullable"
  DateTime next_run_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"quota_counters" {
  String id PK
  String scope_kind
  String scope_id
  String action
  String window
  Int used
  Int limit
  DateTime reset_at
}
"action_tickets" {
  String id PK
  String organization_id
  String app_id "nullable"
  String action
  String minted_by
  String note "nullable"
  String consumed_by_run_id "nullable"
  DateTime consumed_at "nullable"
  DateTime expires_at "nullable"
  DateTime created_at
}
"ai_model_prices" {
  String id PK
  String provider
  String model
  Int tier
  BigInt input_micro_cents_per_mtok
  BigInt output_micro_cents_per_mtok
  Int markup_basis_points "nullable"
  DateTime effective_at
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"credit_ledger_entries" {
  String id PK
  String organization_id FK
  String kind
  BigInt amount_micro_cents
  DateTime expires_at "nullable"
  String source_type "nullable"
  String source_id "nullable"
  String note "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"agent_webhooks" {
  String id PK
  String organization_id
  String app_id
  String agent_id "nullable"
  String user_id "nullable"
  String name
  String secret UK
  Json args_schema "nullable"
  Json automation_pin "nullable"
  String entry_node_urn
  String entry_node_id "nullable"
  Int budget_tokens "nullable"
  Int budget_actions "nullable"
  Json event_data "nullable"
  Json policy "nullable"
  String ai_config_name "nullable"
  String scope_id FK "nullable"
  Boolean enabled
  DateTime last_called_at "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"mcp_session_state" {
  String id PK
  String user_id FK
  String client_key
  String app_id FK "nullable"
  String memory_id FK "nullable"
  String organization_id FK "nullable"
  String scope_id FK "nullable"
  DateTime created_at
  DateTime updated_at "nullable"
}
"urn_aliases" {
  String id PK
  String urn
  UrnAliasEntityType entity_type
  String entity_id
  UrnAliasReason reason
  String replaced_by_urn "nullable"
  DateTime created_at
  String created_by "nullable"
}
"scopes" {
  String id PK
  String name
  String description "nullable"
  String organization_id FK "nullable"
  String agent_id FK "nullable"
  String app_id FK "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"scope_memories" {
  String scope_id FK
  String memory_id FK
  Int position
}
"channels" {
  String id PK
  String memory_id FK
  String loc
  String name
  ChannelKind kind
  String description "nullable"
  String chat_root_node_id FK,UK
  Int last_seq
  DateTime last_message_at "nullable"
  Int incarnation
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"register_entries" {
  String id PK
  String organization_id FK "nullable"
  String app_id FK "nullable"
  String channel_id FK
  String attendee_worker_id FK "nullable"
  String attendee_agent_id FK "nullable"
  RegisterRole role
  Boolean mention_only
  String description "nullable"
  Boolean install_default
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"channel_read_states" {
  String id PK
  String worker_id FK "nullable"
  String agent_id FK "nullable"
  String app_id FK "nullable"
  String channel_id FK
  Int last_seen_seq
  DateTime updated_at
  DateTime last_checked_at "nullable"
  Int channel_incarnation "nullable"
}
"memory_configs" {
  String id PK
  String memory_id FK,UK
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"node_role_rules" {
  String id PK
  String config_id FK
  String role
  String author_task_id FK "nullable"
  Boolean author_task_required
  String validation_task_id FK "nullable"
  Boolean validation_task_required
  String description_node_id FK "nullable"
  Boolean strict_sub_roles
  NodeRoleWriters writers
  ContentValidator validate_by "nullable"
  Boolean enabled
  String source_template_id "nullable"
  Boolean locked
  Int revision
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"memory_config_templates" {
  String id PK
  String name
  String description "nullable"
  Boolean required
  Int revision
  String hadron_server_id FK "nullable"
  String organization_id FK "nullable"
  String owner_user_id FK "nullable"
  String app_id FK "nullable"
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"memory_config_template_rules" {
  String id PK
  String template_id FK
  String role
  String author_task_id FK "nullable"
  Boolean author_task_required
  String validation_task_id FK "nullable"
  Boolean validation_task_required
  String description_node_id FK "nullable"
  Boolean strict_sub_roles
  NodeRoleWriters writers
  ContentValidator validate_by "nullable"
  Boolean enabled
}
"automation_adoption_events" {
  String id PK
  String app_id FK
  String organization_id "nullable"
  String trigger_kind
  String trigger_ref
  String action
  String actor_user_id
  String pin_hash "nullable"
  DateTime created_at
}
"app_memory_write_grants" {
  String id PK
  String app_id FK
  String memory_id FK
  String prefix
  String register_node_urn "nullable"
  String granted_by
  DateTime created_at
  DateTime revoked_at "nullable"
  String revoked_by "nullable"
}
"app_memory_write_grant_events" {
  String id PK
  String app_id FK
  String memory_id
  String grant_id
  String prefix
  String action
  String actor_user_id
  DateTime created_at
}
"app_automation_read_grants" {
  String id PK
  String app_id FK
  String trigger_kind
  String trigger_id
  String memory_id FK
  String prefix "nullable"
  String granted_by
  DateTime created_at
  DateTime revoked_at "nullable"
  String revoked_by "nullable"
}
"app_automation_read_grant_events" {
  String id PK
  String app_id FK
  String trigger_kind
  String trigger_id
  String memory_id
  String grant_id
  String prefix "nullable"
  String action
  String actor_user_id
  DateTime created_at
}
"git_mirror_obligations" {
  String memory_id FK
  String node_id
  GitMirrorObligationKind kind
  String remove_loc
  String branch
  GitMirrorObligationState state
  String error_class
  Int attempts
  BigInt attempt_seq
  DateTime last_attempt_at
}
"automation_versions" {
  String id PK
  String app_id FK
  Int number
  String entry_source_node_id
  String compiled_json
  String version_hash
  Json source_manifest
  AutomationTier tier
  String run_as_user_id "nullable"
  String published_by
  DateTime published_at
  String approval_hash "nullable"
  String approved_by "nullable"
  DateTime approved_at "nullable"
  String revoked_by "nullable"
  DateTime revoked_at "nullable"
}
"agent_tasks" {
  String id PK
  String app_id FK
  BigInt task_number "nullable"
  String handle "nullable"
  String title
  String description "nullable"
  String source "nullable"
  String external_id "nullable"
  String parent_task_id FK "nullable"
  String cloned_from_id FK "nullable"
  String owner_worker_id FK "nullable"
  String owner_user_id FK "nullable"
  String assignee_worker_id FK "nullable"
  String assignee_user_id FK "nullable"
  Json requirements "nullable"
  Boolean match_pending
  DateTime match_failed_at "nullable"
  String match_failed_reason "nullable"
  Json properties "nullable"
  String status
  Int priority
  Boolean blocked
  DateTime released_at "nullable"
  DateTime start_by "nullable"
  DateTime finish_by "nullable"
  DateTime started_at "nullable"
  DateTime finished_at "nullable"
  DateTime cancelled_at "nullable"
  String result_outcome "nullable"
  String result_summary "nullable"
  String result_evidence "nullable"
  Json result_findings "nullable"
  Json finding_dispositions
  String unresolved_finding_ids
  String hand_back_reason_code "nullable"
  String hand_back_reason_text "nullable"
  DateTime handed_back_at "nullable"
  String tags
  Json task_references
  Boolean close_session_when_done
  DateTime assigned_at "nullable"
  String assigned_by "nullable"
  String assigned_by_worker_id "nullable"
  String assigned_by_agent_id "nullable"
  DateTime created_at
  String created_by "nullable"
  String created_by_worker_id "nullable"
  String created_by_agent_id "nullable"
  String created_by_run_id "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  String updated_by_worker_id "nullable"
  String updated_by_agent_id "nullable"
}
"agent_task_blockers" {
  String task_id FK
  String blocker_task_id FK
  DateTime created_at
}
"agent_task_counters" {
  String id PK
  String app_id FK
  String parent_task_id FK "nullable"
  BigInt last_number
}
"agent_team_events" {
  String id PK
  String app_id FK
  String type
  String task_id "nullable"
  String actor_user_id "nullable"
  String actor_worker_id "nullable"
  String actor_agent_id "nullable"
  String actor_run_id "nullable"
  String actor_app_key_id "nullable"
  String subject_worker_id "nullable"
  String subject_user_id "nullable"
  String severity "nullable"
  Json chain "nullable"
  String acknowledged_by_user_id "nullable"
  String acknowledged_by_worker_id "nullable"
  DateTime acknowledged_at "nullable"
  Json payload
  DateTime created_at
  DateTime episode_start "nullable"
}
"agent_team_alarm_schedule" {
  String event_id FK
  Int chain_index
  DateTime due_at
  DateTime woken_at "nullable"
  DateTime ended_at "nullable"
}
"dark_worker_episodes" {
  String id PK
  String app_id FK
  String worker_id FK
  String event_id FK,UK
  String reason
  DateTime opened_at
  DateTime ended_at "nullable"
  DateTime notice_posted_at "nullable"
}
"coordinator_cadence_episodes" {
  String id PK
  String app_id FK
  String worker_id FK
  String event_id FK,UK
  DateTime opened_at
  DateTime ended_at "nullable"
}
"coordinator_cadence_clocks" {
  String worker_id PK,FK
  String app_id FK
  DateTime observed_at
}
"post_limit_episodes" {
  String id PK
  String app_id FK
  String worker_id FK
  String event_id FK,UK
  DateTime opened_at
  DateTime ended_at "nullable"
}
"worker_availability" {
  String worker_id PK,FK
  String state
  String reason "nullable"
  DateTime until "nullable"
  DateTime set_at
  String set_by
  String set_by_user_id "nullable"
  String set_by_worker_id "nullable"
  String set_by_agent_id "nullable"
  String set_by_host_id "nullable"
  DateTime clears_on_activity_after "nullable"
  String context_reset_id "nullable"
}
"model_groups" {
  String id PK
  String name
  String agent_id FK "nullable"
  String app_id FK "nullable"
  String patterns
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
}
"model_family_availability" {
  String app_id FK
  String family
  String state
  String reason "nullable"
  DateTime until "nullable"
  DateTime set_at
  String set_by_user_id "nullable"
  String set_by_worker_id "nullable"
  String set_by_agent_id "nullable"
}
"agent_task_stall_schedule" {
  String app_id PK,FK
  Int not_started_minutes "nullable"
  Int no_progress_minutes "nullable"
  Int owner_reaction_minutes "nullable"
  Int assignment_minutes "nullable"
  Int host_lapse_check_ins "nullable"
  Int session_end_grace_minutes "nullable"
  Int host_report_timeout_minutes "nullable"
  DateTime updated_at
  String updated_by "nullable"
}
"host_registrations" {
  String id PK
  String app_id FK
  String host_id
  String label
  Int poll_interval_seconds
  DateTime registered_at
  DateTime refreshed_at
  DateTime lost_at "nullable"
  String capabilities
}
"host_registration_workers" {
  String registration_id FK
  String worker_id FK
  String family
  String worktrees
}
"host_operations" {
  String id PK
  String app_id FK
  String host_id
  String type
  Json args
  String worker_id FK
  String status
  String issued_by
  String issued_by_user_id "nullable"
  String issued_by_worker_id "nullable"
  String issued_by_agent_id "nullable"
  DateTime issued_at
  DateTime collected_at "nullable"
  DateTime finished_at "nullable"
  Json result "nullable"
  String failure_reason "nullable"
  String hold_user_id "nullable"
  DateTime hold_at "nullable"
}
"resume_claims" {
  String id PK
  String app_id FK
  String session_id
  String worker_id
  String holder_user_id
  DateTime issued_at
  DateTime expires_at
  DateTime consumed_at "nullable"
  String resumed_session_id "nullable"
  DateTime revoked_at "nullable"
}
"launch_grants" {
  String id PK
  String app_id FK
  String operation_id
  String worker_id
  String host_id
  String task_id "nullable"
  String holder_user_id
  String token_hash UK
  DateTime issued_at
  DateTime expires_at
  DateTime consumed_at "nullable"
  String session_id "nullable"
  DateTime revoked_at "nullable"
}
"context_resets" {
  String id PK
  String app_id FK
  String worker_id FK
  String session_id
  String task_id UK
  String host_id "nullable"
  String host_operation_id UK "nullable"
  String phase
  String reason "nullable"
  Int epoch
  DateTime requested_at
  DateTime claimed_at "nullable"
  Json claim_process "nullable"
  Json recovery_ref "nullable"
  DateTime recovery_registered_at "nullable"
  DateTime stop_granted_at "nullable"
  Int stop_lease_ms "nullable"
  DateTime agent_stopped_at "nullable"
  DateTime relaunched_at "nullable"
  Json relaunch_process "nullable"
  DateTime release_pending_at "nullable"
  DateTime ended_at "nullable"
}
"task_session_end_requests" {
  String id PK
  String app_id FK
  String task_id UK
  String worker_id
  String session_id
  String event_id
  String requested_by_worker_id "nullable"
  DateTime requested_at
  DateTime due_at
  DateTime resolved_at "nullable"
  String resolution "nullable"
  String operation_id "nullable"
}
"host_key_uses" {
  String id PK
  String app_key_id FK
  String app_id
  String host_id
  String action
  String operation_id "nullable"
  Int count "nullable"
  String refused_code "nullable"
  DateTime used_at
}
"manual_automation_pins" {
  String run_id PK,FK
  Json pin
  DateTime adopted_at
  String adopted_by "nullable"
}
"tickers" {
  String id PK
  String app_id FK
  String name
  String slug
  String tick_code
  Int cadence_seconds
  DateTime anchor_at
  Json quiet_hours "nullable"
  String channel_ids
  String relevance
  String reasons
  Boolean enabled
  String owner_user_id "nullable"
  String owner_worker_id "nullable"
  String source_template_id "nullable"
  Int source_template_revision "nullable"
  String generated_for_worker_id "nullable"
  DateTime edited_at "nullable"
  DateTime created_at
  String created_by "nullable"
  String created_by_worker_id "nullable"
  String created_by_agent_id "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  String updated_by_worker_id "nullable"
  String updated_by_agent_id "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
  String deleted_by_worker_id "nullable"
  String deleted_by_agent_id "nullable"
}
"agent_ticker_templates" {
  String id PK
  String agent_id FK
  Int revision
  Int shape_version
  String name
  Int cadence_seconds
  Json quiet_hours "nullable"
  String relevance
  String reasons
  DateTime created_at
  String created_by "nullable"
  DateTime updated_at "nullable"
  String updated_by "nullable"
  DateTime deleted_at "nullable"
  String deleted_by "nullable"
}
"ticker_subscriptions" {
  String id PK
  String ticker_id FK
  String worker_id FK
  DateTime created_at
  String created_by "nullable"
  String created_by_worker_id "nullable"
  String created_by_agent_id "nullable"
  String via_grant_id "nullable"
  String via_grant_person_id "nullable"
  DateTime ended_at "nullable"
  String ended_by "nullable"
  String ended_by_worker_id "nullable"
  String ended_by_agent_id "nullable"
  String ended_via_grant_id "nullable"
  String ended_via_grant_person_id "nullable"
  String ended_reason "nullable"
}
"worker_wake_settings" {
  String worker_id PK,FK
  String mentions
  DateTime paused_until "nullable"
  DateTime isolated_until "nullable"
  DateTime isolated_at "nullable"
  String isolated_by_user_id "nullable"
  DateTime exempt_ended_at "nullable"
  DateTime updated_at
  String updated_by "nullable"
  String updated_by_worker_id "nullable"
  String updated_by_agent_id "nullable"
}
"worker_delivery_channels" {
  String worker_id FK
  String channel_id
  Int channel_incarnation
  Int delivered_through_seq
  DateTime delivered_at
  String acked_by_user_id "nullable"
  String acked_by_worker_id "nullable"
  String acked_by_app_key_id "nullable"
}
"worker_wake_acks" {
  String worker_id FK
  String wake_key
  DateTime acked_at
  DateTime issued_at "nullable"
  String acked_by_user_id "nullable"
  String acked_by_worker_id "nullable"
  String acked_by_app_key_id "nullable"
}
"worker_delivery_ticks" {
  String worker_id FK
  String ticker_id FK
  Int last_acked_tick
  DateTime acked_at
  String acked_by_user_id "nullable"
  String acked_by_worker_id "nullable"
  String acked_by_app_key_id "nullable"
}
"worker_delivery_task_events" {
  String worker_id FK
  String event_id FK
  Int chain_index
  DateTime delivered_at "nullable"
  String acked_by_user_id "nullable"
  String acked_by_worker_id "nullable"
  String acked_by_app_key_id "nullable"
  DateTime undeliverable_at "nullable"
  String undeliverable_reason "nullable"
}
"app_wake_days" {
  String app_id FK
  DateTime day
  Int wakes
  DateTime notice_posted_at "nullable"
}
"app_wake_reservations" {
  String worker_id PK,FK
  String app_id FK
  DateTime reserved_at
  String wake_key
  Json wake
  String absorbed_keys
}
"team_stop_signals" {
  String id PK
  String app_id FK
  String level
  String scope
  String target_worker_id FK "nullable"
  String target_host_registration_id FK "nullable"
  DateTime set_at
  DateTime until "nullable"
  String set_by_user_id "nullable"
  String set_by_app_key_id "nullable"
  DateTime ended_at "nullable"
  String end_kind "nullable"
  String ended_by_user_id "nullable"
  String ended_by_app_key_id "nullable"
}
"stop_consumer_declarations" {
  String app_id FK
  String lane
  DateTime declared_at
}
"team_stop_coverage" {
  String id PK
  String app_id
  String signal_id FK
  String worker_id
  DateTime entered_at
  DateTime left_at "nullable"
}
"agent_task_stop_holds" {
  String id PK
  String app_id
  String task_id FK
  DateTime started_at
  DateTime ended_at "nullable"
}
"app_grants" {
  String id PK
  String app_id FK
  String grantee_worker_id FK
  String name
  DateTime granted_at
  String granted_by "nullable"
  DateTime revoked_at "nullable"
  String revoked_by "nullable"
}
"app_key_scopes" {
  String id PK
  String app_key_id FK
  String scope
  String granted_by_user_id
  DateTime granted_at
  String revoked_by_user_id "nullable"
  DateTime revoked_at "nullable"
  String host_id "nullable"
}
"app_key_wake_reads" {
  String id PK
  String app_key_id FK
  String app_id
  Int worker_count
  DateTime read_at
}
"user_deletion_audits" {
  String id PK
  String actor_user_id
  String target_user_id UK
  String reason
  DateTime completed_at
}
"user_deletion_notices" {
  String audit_id PK,FK
  UserDeletionNoticeStatus status
  String recipient_ciphertext "nullable"
  Int attempts
  DateTime lease_until "nullable"
  String claim_token "nullable"
  DateTime created_at
  DateTime updated_at
}
"worker_reference_fences" {
  String subject_id PK
  BigInt version
}
"served_prompts" {
  String id PK
  ServedPromptKind kind
  String session_id "nullable"
  String chat_id "nullable"
  String run_id "nullable"
  Int ordinal
  String app_id "nullable"
  String agent_id
  String worker_id "nullable"
  ServedPromptPointerLevel pointer_level
  String compiled_node_id
  Int served_rev_seq
  Int provenance_rev_seq
  String compiled_content_hash
  Json provenance
  Json variables
  DateTime served_at
}
"agent_clone_audits" {
  String id PK
  String actor_user_id "nullable"
  String source_agent_id
  String new_agent_id
  String target_org_id "nullable"
  String target_user_id "nullable"
  Int node_count
  Int edge_count
  Int skipped_edge_count
  Int import_count
  Int link_count
  DateTime created_at
}
"node_edge_removals" {
  String id PK
  String source_id FK
  String memory_id
  String edge_id
  String edge_loc
  String edge_name "nullable"
  String target_id
  String target_memory_id
  String target_loc
  String reason
  String removed_by "nullable"
  DateTime created_at
}
"asset_public_link_audits" {
  String id PK
  String asset_id
  String memory_id
  String actor_user_id
  Boolean enabled
  Boolean previously_enabled
  DateTime created_at
}
"include_references" {
  String id PK
  String includer_id FK
  Int ordinal
  IncludeReferenceKind kind
  String reference
  String target_memory_id "nullable"
  String target_loc "nullable"
  Int pinned_rev_no "nullable"
  Boolean requires_approved
  Boolean requires_signed
  Int metadata_generation
}
"include_source_coverage" {
  String id PK
  String includer_id FK,UK
  Int source_revision
  String source_memory_id
  String source_loc
  String source_content_fingerprint
  Boolean source_encrypted
  Int parser_version
  Int metadata_generation
  Int reference_count
  IncludeSourceCoverageState state
}
"include_retention_generation" {
  String id PK
  Int schema_version
  Int parser_version
  Int metadata_generation
  IncludeRetentionState state
  String source_high_water_id "nullable"
  String replay_cursor "nullable"
  Int binding_generation
  Int verified_binding_generation "nullable"
  Int source_count
  Int covered_count
  Int blocked_count
}
"rate_limit_policies" {
  String field_class PK
  Int principal_limit
  Int key_limit
  Int ip_limit
  Int window_seconds
  Int retention_seconds
  String enforcement_mode
  Int version
  DateTime updated_at
}
"rate_limit_buckets" {
  String id PK
  String field_class
  String dimension
  String subject
  DateTime window_start
  BigInt used
  DateTime expires_at
}
"rate_limit_manifests" {
  String id PK
  String key_ids
  Json fingerprints
  DateTime overlap_started_at "nullable"
  Int version
}
"rate_limit_policy_audits" {
  String id PK
  String field_class
  String actor_id
  Json before
  Json after
  String change_reference
  DateTime created_at
}
"_AppToUser" {
  String A FK
  String B FK
}
"users" }o--o| "apps" : externalApp
"users" |o--o| "principals" : principal
"user_merges" |o--|| "users" : source
"user_merges" }o--|| "users" : target
"dashboard_widgets" }o--|| "users" : user
"dashboard_widget_presets" }o--|| "users" : user
"organizations" |o--o| "principals" : principal
"org_members" }o--|| "organizations" : organization
"org_members" }o--|| "users" : user
"memories" }o--o| "users" : ownerUser
"memories" }o--o| "organizations" : organization
"memories" }o--o| "agents" : userMemoryOfAgent
"memories" }o--o| "agents" : sharedMemoryOfAgent
"memories" }o--o| "agents" : installOfAgent
"memories" }o--o| "users" : user
"memories" }o--o| "apps" : app
"assets" }o--o| "memories" : memory
"nodes" }o--|| "memories" : memory
"node_embeddings" }o--|| "nodes" : node
"node_embeddings" }o--|| "memories" : memory
"edges" }o--|| "memories" : memory
"edges" }o--|| "nodes" : source
"edges" }o--|| "nodes" : target
"comment_meta" |o--|| "nodes" : node
"comment_meta" }o--|| "nodes" : target
"pending_edges" }o--|| "nodes" : source
"sessions" }o--o| "sessions" : parent
"sessions" }o--o| "sessions" : prev
"sessions" }o--o| "apps" : app
"sessions" }o--o| "users" : user
"sessions" }o--o| "agents" : agent
"sessions" }o--o| "workers" : worker
"sessions" }o--o| "memories" : memory
"usage_events" }o--o| "nodes" : node
"usage_events" }o--o| "sessions" : session
"usage_events" }o--o| "apps" : app
"usage_events" }o--o| "users" : user
"usage_events" }o--o| "organizations" : organization
"agents" }o--o| "users" : ownerUser
"agents" }o--o| "organizations" : organization
"agents" }o--o| "agents" : extendsAgent
"agents" }o--o| "nodes" : tasksIndex
"agents" }o--o| "nodes" : processesIndex
"agent_memory_items" }o--|| "agents" : agent
"agent_memory_items" }o--|| "memories" : memory
"memory_licenses" }o--|| "memories" : memory
"memory_subscriptions" }o--|| "memories" : memory
"memory_subscriptions" }o--|| "organizations" : organization
"memory_subscriptions" }o--o| "memory_licenses" : license
"ai_service_configs" }o--o| "hadron_server" : hadronServer
"ai_service_configs" }o--o| "organizations" : organization
"ai_service_configs" }o--o| "apps" : app
"ai_service_configs" }o--o| "agents" : agent
"server_log" }o--|| "hadron_server" : server
"memory_log" }o--|| "memories" : memory
"org_member_invitations" }o--|| "org_members" : sender
"org_member_invitations" }o--|| "users" : recipient
"user_invitations" }o--o| "users" : sender
"user_invitations" }o--o| "organizations" : organization
"user_invitation_activations" }o--|| "user_invitations" : invitation
"user_invitation_activations" }o--|| "users" : user
"compiled_prompt_revisions" }o--|| "nodes" : compiledNode
"node_revisions" }o--|| "nodes" : node
"node_revisions" }o--o| "users" : approvedByUser
"node_content_validation_reports" }o--|| "nodes" : node
"pending_setups" |o--|| "users" : user
"pending_setups" }o--|| "apps" : app
"exchange_connections" }o--|| "organizations" : organization
"exchange_connections" }o--|| "users" : user
"connection_flows" }o--|| "users" : user
"connection_flows" }o--|| "organizations" : organization
"connection_grants" }o--|| "exchange_connections" : connection
"connection_grants" }o--|| "apps" : granteeApp
"connection_grants" }o--|| "users" : grantedBy
"principal_grants" }o--|| "users" : principal
"principal_grants" }o--|| "organizations" : organization
"slack_connections" }o--|| "organizations" : organization
"slack_connections" }o--|| "apps" : defaultApp
"webfetch_poll_bindings" }o--|| "app_runs" : sourceRun
"webfetch_event_receipts" }o--|| "app_runs" : routedRun
"mcp_servers" }o--|| "organizations" : organization
"home_assistant_instances" }o--|| "organizations" : organization
"resend_senders" |o--|| "organizations" : organization
"apps" }o--o| "users" : ownerUser
"apps" }o--o| "organizations" : organization
"apps" |o--o| "channels" : defaultChannel
"app_keys" }o--|| "apps" : app
"app_members" }o--|| "apps" : app
"app_members" }o--|| "users" : user
"agent_org_grants" }o--|| "organizations" : organization
"agent_org_grants" }o--|| "agents" : agent
"agent_imports" }o--|| "agents" : parentAgent
"agent_imports" }o--|| "agents" : importedAgent
"agent_imports" }o--|| "agent_org_grants" : agentOrgGrant
"agent_subscriptions" }o--|| "users" : user
"agent_subscriptions" }o--|| "agents" : agent
"app_log" }o--|| "apps" : app
"app_agents" }o--|| "apps" : app
"app_agents" }o--|| "agents" : agent
"workers" }o--|| "apps" : app
"workers" }o--o| "workers" : reportsTo
"workers" }o--|| "agents" : agent
"workers" }o--o| "memories" : memory
"workers" }o--o| "users" : heldBy
"memory_shares" }o--|| "memories" : memory
"memory_shares" }o--|| "users" : grantee
"memory_shares" }o--|| "users" : grantor
"memory_members" }o--|| "memories" : memory
"memory_members" }o--|| "users" : user
"user_api_keys" }o--o| "user_api_keys" : mintedByKey
"user_api_keys" }o--o| "sign_ins" : originSignIn
"user_api_keys" }o--|| "users" : user
"impersonation_sessions" }o--|| "users" : adminUser
"impersonation_sessions" }o--|| "users" : targetUser
"impersonation_sessions" }o--|| "organizations" : organization
"auth_codes" }o--|| "users" : user
"auth_codes" }o--|| "oauth_clients" : client
"auth_codes" }o--o| "sign_ins" : signIn
"passkey_ceremonies" }o--o| "users" : user
"passkey_ceremonies" }o--o| "passkey_credentials" : vouchPasskey
"passkey_registration_notices" |o--|| "passkey_credentials" : passkey
"passkey_registration_notices" }o--|| "users" : user
"passkey_cancel_tokens" |o--|| "passkey_credentials" : passkey
"fresh_sign_ins" }o--|| "users" : user
"pending_email_sign_ins" }o--|| "users" : user
"pending_email_sign_ins" }o--o| "sign_ins" : signIn
"passkey_credentials" }o--|| "users" : owner
"user_api_key_deletions" }o--|| "users" : user
"sign_ins" }o--|| "users" : user
"sign_ins" }o--o| "passkey_credentials" : passkey
"signing_requests" }o--|| "nodes" : node
"node_signatures" }o--|| "nodes" : node
"node_signatures" |o--|| "signing_requests" : signingRequest
"node_signatures" }o--|| "passkey_credentials" : passkey
"auth_handoff_codes" }o--|| "users" : user
"auth_handoff_codes" }o--o| "sign_ins" : signIn
"agent_schedules" }o--o| "scopes" : scope
"credit_ledger_entries" }o--|| "organizations" : organization
"agent_webhooks" }o--o| "scopes" : scope
"mcp_session_state" }o--|| "users" : user
"mcp_session_state" }o--o| "apps" : app
"mcp_session_state" }o--o| "memories" : memory
"mcp_session_state" }o--o| "organizations" : organization
"mcp_session_state" }o--o| "scopes" : scope
"scopes" }o--o| "organizations" : organization
"scopes" }o--o| "agents" : agent
"scopes" }o--o| "apps" : app
"scope_memories" }o--|| "scopes" : scope
"scope_memories" }o--|| "memories" : memory
"channels" }o--|| "memories" : memory
"channels" |o--|| "nodes" : chatRoot
"register_entries" }o--o| "organizations" : organization
"register_entries" }o--o| "apps" : app
"register_entries" }o--|| "channels" : channel
"register_entries" }o--o| "workers" : attendeeWorker
"register_entries" }o--o| "agents" : attendeeAgent
"channel_read_states" }o--o| "workers" : worker
"channel_read_states" }o--o| "agents" : agent
"channel_read_states" }o--o| "apps" : app
"channel_read_states" }o--|| "channels" : channel
"memory_configs" |o--|| "memories" : memory
"node_role_rules" }o--|| "memory_configs" : config
"node_role_rules" }o--o| "nodes" : authorTask
"node_role_rules" }o--o| "nodes" : validationTask
"node_role_rules" }o--o| "nodes" : descriptionNode
"memory_config_templates" }o--o| "hadron_server" : hadronServer
"memory_config_templates" }o--o| "organizations" : organization
"memory_config_templates" }o--o| "users" : ownerUser
"memory_config_templates" }o--o| "apps" : app
"memory_config_template_rules" }o--|| "memory_config_templates" : template
"memory_config_template_rules" }o--o| "nodes" : authorTask
"memory_config_template_rules" }o--o| "nodes" : validationTask
"memory_config_template_rules" }o--o| "nodes" : descriptionNode
"automation_adoption_events" }o--|| "apps" : app
"app_memory_write_grants" }o--|| "apps" : app
"app_memory_write_grants" }o--|| "memories" : memory
"app_memory_write_grant_events" }o--|| "apps" : app
"app_automation_read_grants" }o--|| "apps" : app
"app_automation_read_grants" }o--|| "memories" : memory
"app_automation_read_grant_events" }o--|| "apps" : app
"git_mirror_obligations" }o--|| "memories" : memory
"automation_versions" }o--|| "apps" : app
"agent_tasks" }o--|| "apps" : app
"agent_tasks" }o--o| "agent_tasks" : parent
"agent_tasks" }o--o| "agent_tasks" : clonedFrom
"agent_tasks" }o--o| "workers" : ownerWorker
"agent_tasks" }o--o| "users" : ownerUser
"agent_tasks" }o--o| "workers" : assigneeWorker
"agent_tasks" }o--o| "users" : assigneeUser
"agent_task_blockers" }o--|| "agent_tasks" : task
"agent_task_blockers" }o--|| "agent_tasks" : blocker
"agent_task_counters" }o--|| "apps" : app
"agent_task_counters" }o--o| "agent_tasks" : parentTask
"agent_team_events" }o--|| "apps" : app
"agent_team_alarm_schedule" }o--|| "agent_team_events" : event
"dark_worker_episodes" }o--|| "apps" : app
"dark_worker_episodes" }o--|| "workers" : worker
"dark_worker_episodes" |o--|| "agent_team_events" : event
"coordinator_cadence_episodes" }o--|| "apps" : app
"coordinator_cadence_episodes" }o--|| "workers" : worker
"coordinator_cadence_episodes" |o--|| "agent_team_events" : event
"coordinator_cadence_clocks" }o--|| "apps" : app
"coordinator_cadence_clocks" |o--|| "workers" : worker
"post_limit_episodes" }o--|| "apps" : app
"post_limit_episodes" }o--|| "workers" : worker
"post_limit_episodes" |o--|| "agent_team_events" : event
"worker_availability" |o--|| "workers" : worker
"model_groups" }o--o| "agents" : agent
"model_groups" }o--o| "apps" : app
"model_family_availability" }o--|| "apps" : app
"agent_task_stall_schedule" |o--|| "apps" : app
"host_registrations" }o--|| "apps" : app
"host_registration_workers" }o--|| "host_registrations" : registration
"host_registration_workers" }o--|| "workers" : worker
"host_operations" }o--|| "apps" : app
"host_operations" }o--|| "workers" : worker
"resume_claims" }o--|| "apps" : app
"launch_grants" }o--|| "apps" : app
"context_resets" }o--|| "apps" : app
"context_resets" }o--|| "workers" : worker
"task_session_end_requests" }o--|| "apps" : app
"host_key_uses" }o--|| "app_keys" : appKey
"manual_automation_pins" |o--|| "app_runs" : run
"tickers" }o--|| "apps" : app
"agent_ticker_templates" }o--|| "agents" : agent
"ticker_subscriptions" }o--|| "tickers" : ticker
"ticker_subscriptions" }o--|| "workers" : worker
"worker_wake_settings" |o--|| "workers" : worker
"worker_delivery_channels" }o--|| "workers" : worker
"worker_wake_acks" }o--|| "workers" : worker
"worker_delivery_ticks" }o--|| "workers" : worker
"worker_delivery_ticks" }o--|| "tickers" : ticker
"worker_delivery_task_events" }o--|| "workers" : worker
"worker_delivery_task_events" }o--|| "agent_team_events" : event
"app_wake_days" }o--|| "apps" : app
"app_wake_reservations" }o--|| "apps" : app
"app_wake_reservations" |o--|| "workers" : worker
"team_stop_signals" }o--|| "apps" : app
"team_stop_signals" }o--o| "workers" : targetWorker
"team_stop_signals" }o--o| "host_registrations" : targetHost
"stop_consumer_declarations" }o--|| "apps" : app
"team_stop_coverage" }o--|| "team_stop_signals" : signal
"agent_task_stop_holds" }o--|| "agent_tasks" : task
"app_grants" }o--|| "apps" : app
"app_grants" }o--|| "workers" : grantee
"app_key_scopes" }o--|| "app_keys" : appKey
"app_key_wake_reads" }o--|| "app_keys" : appKey
"user_deletion_notices" |o--|| "user_deletion_audits" : audit
"node_edge_removals" }o--|| "nodes" : source
"include_references" }o--|| "nodes" : includer
"include_source_coverage" |o--|| "nodes" : includer
"_AppToUser" }o--|| "apps" : App
"_AppToUser" }o--|| "users" : User

users

A person who uses Hadron, authenticated via GitHub OAuth (or email in future). N:N to Organization via OrgMember. (Spec 048: signup no longer auto-creates a personal organization — an individual owns Apps/Agents/Memories directly via spec 047 user-owned tenancy.)

Invitation chain: UserInvitationActivation links each User back to their UserInvitation, whose senderUserId points to the inviter, recursively up to the root (senderUserId IS NULL = system seed from Baragaun).

Referral quota (maxReferrals): the maximum number of new platform users this user is allowed to onboard. Unaccepted invitations don't count; the count is on accepted activations only. Quota is tracked transitively up the chain — if A invites B and B invites C, both A's and B's quotas decrement when C joins. When sending an invite, UserInvitation.maxActivations must not exceed the minimum free quota across the inviter's referral chain. There is a known race condition: if a referral starts onboarding and the "create account" request would push the chain over quota, the account is still created (don't block a real human on a counter).

Properties as follows:

  • id:
  • handle

    Unique username, e.g. "holger"; displayed as @holger in UI and node frontmatter author field, and the owner namespace of a user-owned App/Agent/Memory URN (spec 047). NOT NULL (all users backfilled 2026-07-14): every real signup path assigns one via generateUniqueHandle; the DB-generated random default is a backstop for handle-omitting inserts (test fixtures) so those need no churn. Case-insensitive uniqueness is the users_handle_lower_uniq functional index (post-push.sql); the @unique here is the plain case-sensitive one.

  • policy

    User-layer action-policy link (cor:acl:040:02) — constrains runs made on-behalf-of this user. Same allow-list shape as Organization.policy; NULL = no restriction. Self-authored (updateMyPolicy).

  • github_id: GitHub numeric account id.
  • github_username: GitHub login.
  • google_id

    Google account id — the OIDC sub claim (#581). A string of digits, but stored as text: Google documents it as an opaque string and it can exceed 2^53.

  • apple_id

    Apple account id — the Sign-in-with-Apple sub claim (#584). An opaque team-scoped string (e.g. "001234.abcd1234ef….0102").

  • identity_provider:
  • external_id: App-scoped external user id. Composite-unique with externalAppId.
  • external_app_id

    The App that minted this externalId. Forms a (App, externalId) idempotency key for chatbot user provisioning.

  • linked_at

    When this app-scoped external identity was linked to the platform User (i.e. when the chatbot user "graduated" to a real account).

  • name:
  • email: Used for invite matching and email-based auth.
  • avatar_url:
  • roles: Global platform roles (not org-scoped). Default [READER].
  • max_referrals

    Maximum number of new platform users this user can onboard. See the model-level doc for the referral-quota semantics.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • principal_id:

user_merges

1715 — one account merge (mergeUsers): the source account was merged

into the target, which survives. Written in the merge transaction and never changed, so it is keyed on the source: an account is merged away at most once (it is soft-deleted, so it can never be a merge's target later, which also keeps the chains acyclic).

Records that store user ids inside authenticated data (decision and decision-log payloads, #1641) are never rewritten by a merge. Readers follow a stored id through these rows, transitively, to the account that survives (src/lib/userMerges.ts). So targetUserId is deliberately NOT retargeted by a later merge of the target: the chain is what resolves it.

Properties as follows:

  • source_user_id:
  • target_user_id:
  • merged_at:
  • merged_by: The acting admin at the merge. Null only on historical merge records.
  • consent_hash: #1642: sealed dual-login consent evidence; absent only on historical merges.
  • consent_receipt:

user_merge_consents

1642: a single-use approval for one ordered, full-account consolidation.

User ids are sealed snapshots, deliberately not retargeted on later merges.

Properties as follows:

  • id:
  • proof_hash:
  • source_user_id:
  • target_user_id:
  • requested_by:
  • scope:
  • created_at:
  • expires_at:
  • source_login_at:
  • source_login_method:
  • target_login_at:
  • target_login_method:
  • consumed_at:

dashboard_widgets

A widget the user has placed on their /app/dashboard grid (#772) — user-scoped layout configuration, one row per placed widget, ordered by position. Owner-only: no org, no sharing. The whole set is read via dashboardWidgets and replaced atomically via setDashboardWidgets.

Properties as follows:

  • id:
  • user_id:
  • type:
  • span: Columns to span on the 12-col desktop grid (clamped on smaller screens).
  • row_span: Rows to span on the fixed-height row grid (#788; clamped server-side to 1-4).
  • config

    Widget-instance settings, shape widget-defined (#788) — e.g. a stats widget scoped to one org. Stored + round-tripped only; no server-side behavior until dashboardWidgetData goes per-instance.

  • position: 0-based sort order among the user's widgets.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

dashboard_widget_presets

A named, user-scoped widget configuration (#806) — a palette entry the portal COPIES into a placement's config on apply. Deliberately not a live link: editing a preset never reaches back into placements already seeded from it, and deleting one never orphans a placement. Generic over widget types so the next configurable widget inherits the mechanism.

Owner-only in every direction, like DashboardWidget: no org, no sharing.

Properties as follows:

  • id:
  • user_id:
  • type:
  • name: Display name, unique per (user, type). Trimmed, 1-60 chars.
  • config

    The saved settings, shape widget-defined — same 4KB cap and plain-object guard as a placement's config, since it becomes one verbatim.

  • created_at:
  • updated_at:

organizations

A company, team, or group that owns memories and has members. Must have at least one OrgMember with role OWNER (can have many).

Properties as follows:

  • id:
  • name:
  • urn

    The organization's domain name, e.g. "baragaun.com", "micromentor.org". Serves as the namespace for all resources owned by this org (URN prefix).

  • listed_on_marketplace

    Opt-in marketplace catalogue flag (cor:acl:080:04): whether this org is advertised in the marketplace browse. DISTINCT from access/visibility — it governs advertisement, not who may read the org. Contributes to non-member discoverability (cor:acl:080:02). (Spec 048 dropped the former isVisible listing flag with the auto-personal org — every org now lists.)

  • github_installation_id

    GitHub App installation id. Used to mint ephemeral tokens (1-hour expiry) for memory git-sync against repos within this installation's scope.

  • github_app_id:
  • github_app_private_key_encrypted

    AES-256-GCM-encrypted GitHub App private key. Plaintext never stored or shown after initial entry. Encryption key: HADRON_ENCRYPTION_KEY env var.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • policy

    Org-layer action-policy link of the conjunctive chain (cor:acl:040:02): allow-list JSON { "allow": ["action", "prefix.*", "*"] }. NULL = no restriction (the layer is absent, not deny-all). Snapshotted into AppRun.policy at mint — edits apply to FUTURE runs only.

  • principal_id:

principals

692 — the unified per-server PRINCIPAL POOL. One row per root name (a user

handle OR an organization name), enforcing CROSS-KIND uniqueness by constraint so a URN <root> atom resolves to exactly one principal without an @ sigil or kind marker (GitHub's model). Users and Organizations FK into this; their own handle / urn columns stay the denormalized read source-of-truth, kept in sync inside the mint transaction.

A released root name is TOMBSTONED (status = 'released', the owning user/org detached) — the row is kept, and the name @unique spans ALL statuses, so a released name is reserved FOREVER (indefinite, no recycling — the identity guarantee the @-sigil rename-safety is replaced by). Reserved platform words (hadron, platform, …) are pre-seeded rows with status = 'reserved'. name is written lowercased everywhere, so the plain (Prisma-modeled) unique doubles as case-insensitive and backs findUnique.

Properties as follows:

  • id:
  • name

    The canonical root name, stored lowercase. @unique is a plain (case- sensitive) index, which is sufficient because every write lowercases the name (mintPrincipal + the migration backfill) — so it is effectively case-insensitive AND index-backed for the findUnique availability probe. Spans ALL statuses (no status filter), so a released tombstone reserves its name forever (indefinite, no recycling).

  • kind: 'user' | 'org' | 'platform'.
  • status: 'active' | 'released' (tombstone) | 'reserved' (platform word).
  • released_at:
  • created_at:
  • updated_at:

org_members

Associates a User with an Organization. To remove a User from an Organization, delete the OrgMember row. Must NOT delete the OrgMember if it is the only one with role OWNER (enforced at the resolver, not the schema).

Properties as follows:

  • id:
  • organization_id:
  • user_id:
  • role:
  • can_invite

    Whether this member can invite other existing platform users to the organization. Inviting a new platform user (UserInvitation) is governed separately by User.maxReferrals.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

memories

A Hadron knowledge graph, owned by an Organization. The four-way class field (system / app / knowledge / personal) governs addressing and access — see the MemoryClass enum doc.

Git-backed memories — the root node.yaml in the repo is the memory manifest, declaring the memory's urn and marketplace metadata. On import the server reads this manifest and creates or updates the Memory row. The org portion of the URN must match an existing Organization on the server.

Git authentication — the server first tries the owning Organization's githubInstallationId to mint ephemeral tokens (1-hour expiry). If the repo is outside the GitHub App's scope (different GitHub org, personal repo, GitLab, etc.), the server falls back to sourceTokenEncrypted. The GitHub App's private key (used to sign JWT requests for installation tokens) lives in the server's environment/secrets manager — not in the database. For the SaaS server, Baragaun manages this key.

Token encryption — sourceTokenEncrypted uses AES-256-GCM with a symmetric key from the server's environment (HADRON_ENCRYPTION_KEY). Plaintext never stored or shown after initial entry. To replace an expired/revoked token, the user pastes a new one (overwrites the old encrypted value). Key rotation: re-encrypt all stored tokens with the new key in a single migration.

Properties as follows:

  • id:
  • organization_id:
  • owner_user_id

    The user TENANT owner of a user-owned Memory (rooted on the bare <handle> — #697 v2, no @ sigil). DISTINCT from userId (the personal/private strict-owner). The exactly-one-of organizationId/ownerUserId XOR is ENFORCED — chk_memory_owner_xor in post-push.sql: (organization_id IS NULL) <> (owner_user_id IS NULL) — so exactly one is non-null (the URN backfill dispatches owner KIND off it; don't add a redundant ambiguity branch).

  • app_id

    The App this memory belongs to. Required when class is app; optional for knowledge/group/personal/private (set when app-scoped, NULL when free-standing); NULL for system. Enforced by chk_memory_class_app_id (#653 allowed knowledge + group to attach to an App).

  • user_id

    Owning user for personal/private-class memories. Bidirectional invariant (CHECK chk_personal_visibility_user): class IN ('personal','private') ⇔ userId IS NOT NULL.

  • user_memory_of_agent_id

    Agent pivot used by live access-control and memory classification. With a calling App, legacy personal/private rows with appId NULL require this Agent installed; agent-scoped AgentSubscription checks use this Agent too. Marks per-user/session/anonymous holdings for exclusion from shared App/team memory folds. Free-standing personal/private memories leave this and appId NULL.

  • shared_memory_of_agent_id

    723 — the IDENTITY of an App's shared app-class memory: the Agent whose

    shared space this is, under appId. Set ONLY on that runtime memory (NULL on every other row, including the name-addressable createMemoryInApp app-class memories), so @@unique([appId, sharedMemoryOfAgentId]) is the find-or-create key for findOrCreateAppClassMemory — Postgres treats NULLs as distinct, so unset rows are unconstrained. Before #723 that identity was the URN STRING (<app-urn>:<agent-slug>:shared), which forced the row to keep a compound v1 URN (node URNs inside it could not round-trip through splitNodeUrn, so portal links to them 404'd) and silently orphaned the memory when its App was renamed. Enforced by chk_memory_shared_agent_scope (set ⇒ class='app' AND app_id IS NOT NULL).

  • install_of_agent_id

    2044 (S7) — the IDENTITY of an App's INSTALL MEMORY: the Agent this

    class='system' row customises for appId (cor:agt:040:06). Set ONLY there; NULL on every other row, including an Agent's own system memory (which is app_id IS NULL and is reached through Agent.systemMemoryId, a pointer an install memory never has). Identity is by COLUMNS, never by URN, so a renamed App or Agent cannot orphan it. One LIVE row per (app_id, install_of_agent_id): the partial unique index lives in prisma/post-push.sql (Prisma cannot model the WHERE). Enforced by chk_memory_class_app_id (system ⇒ both set or both NULL).

  • is_install_memory

    R94 C (#2064): TRUE for an App's install memory, for its whole life. The link to the Agent above is NULLed when the Agent is erased with its owner's account (the memory stays with its App, a detached install), so the discriminator every gate branches on cannot be that link. Enforced by chk_memory_class_app_id: class='system' with an app_id ⇔ TRUE.

  • urn

    Globally unique identifier, e.g. "baragaun.com:secureid". Derived from org.urn + ":" + slug.

  • name: Human-friendly display name, e.g. "SecureID Service".
  • short_description: One-line summary for marketplace listings and search results.
  • description: Full description (markdown); shown when expanding a listing.
  • data

    Free-form structured metadata for this memory — a client-defined JSON bag with no server-side semantics. Written via the GraphQL createMemory / updateMemory mutations; surfaced read-only over MCP (hadron_list_memories renders it as a data: line). The MCP surface has no memory-mutation tool, so writes stay GraphQL-only. NULL when unset.

  • schema

    725 — opt-in per-memory PROPERTY SCHEMA (structured storage): the

    collections (object types) this memory declares and each one's typed fields. A dedicated column (NOT nested in data) so a schema'd memory is visible at a glance. Shape + well-formedness validated by src/lib/memorySchema.ts; authored via updateMemory (GraphQL/portal), read-only over MCP for discovery. NULL ⇒ no schema (unstructured). Node properties/objectType are validated against it in the enforcement phase (a later PR) — free-form until then.

  • corpus_draft

    1591 — legacy whole-corpus flag retained for compatibility. Draft rights

    now belong to each node and end at its first mint; false does not mean every node in this memory is minted. Minting still clears this flag.

  • corpus_minted_at

    1591 — legacy record of the latest nonempty mint in this memory and its

    actor. Node mint records determine mint state; this stamp confers no memory-wide removal protection or draft rights.

  • corpus_minted_by:
  • tags: Classification tags for search and filtering.
  • license: License identifier (e.g. "MIT", "CC-BY-4.0", "proprietary").
  • category_0: Primary category (e.g. "Developer Tools").
  • category_1: Secondary category (e.g. "Backend").
  • category_2: Tertiary category (e.g. "Node.js").
  • icon_url: Square icon/logo URL for listings.
  • hero_url: Banner image URL for the detail page.
  • home_url: External homepage or documentation URL.
  • source: Git clone URL; null = DB-only mode (no git backing).
  • source_token_encrypted

    AES-256-GCM-encrypted access token for repos not covered by the org's GitHub App installation (e.g. personal repos, GitLab, Bitbucket). Plaintext never stored or displayed after initial entry.

  • source_token_expires_at

    Expiry of the stored token; server warns via MemoryLogEntry before expiration.

  • read_branch: Branch to clone/pull from (default: repo default branch).
  • read_branch_corrected

    1566: false until one safe sync using the corrected branch commits.

    This is conservative for both existing and newly created memories.

  • write_branch: Branch for mutations (default: "hadron-updates").
  • visibility

    035-visibility-enum-cleanup: nullable, no default. Set only for knowledge (PUBLIC/ORGANIZATION) and group (GROUP); NULL for system/app/personal/private (enforced by chk_memory_visibility_class).

  • listed_on_marketplace

    Opt-in marketplace catalogue flag (cor:acl:080:04): whether this memory is advertised in the marketplace browse. DISTINCT from visibility — PUBLIC governs access (reachable by URN), this governs advertisement. "Unlisted but public" is valid; contributes to the owner org's discoverability (cor:acl:080:02).

  • is_encrypted

    Whether the memory's contents (including asset bytes) are encrypted at rest using AES-256-GCM under HADRON_ENCRYPTION_KEY.

  • class

    Per-class governance — see MemoryClass enum doc for the four classes and their addressing rules.

  • anonymous_expires_at

    When an anonymous (pre-account-creation) memory expires and is reaped by the janitor. NULL for non-anonymous memories.

  • requires_license: If true, any subscription must have a valid MemoryLicense.
  • last_synced_at: Last successful git sync.
  • sync_status:
  • sync_error: Error message from the last failed sync.
  • last_sync_report: Versioned last completed sync outcome; null after a clean sync (or before any sync).
  • pending_edge_count

    Number of live unresolved PendingEdge records whose live source is in this memory (a derived projection, denormalized for dashboard display).

  • accepts_uploads

    Whether this memory accepts asset uploads. system-class memories typically opt out.

  • vector_index_enabled

    Opt-in: when true, this memory's nodes are vector-indexed. DB default is false; the class-derived default is applied at createMemory — a knowledge-class, non-encrypted memory is created with true, all other classes and any encrypted memory stay false (FR-001). Flippable per memory.

  • embedding_source

    What the vector index is built from. Memory property, NOT a query parameter (FR-002). Only meaningful when vectorIndexEnabled.

  • chunk_tokens

    Per-memory chunking dials (FR-003). NULL ⇒ platform default (512 / 64). Consulted only when embeddingSource includes chunks.

  • chunk_overlap:
  • force_fixed_size: Force fixed-size chunking, bypassing structure-aware (FR-015).
  • max_rev_count

    621 — cap on how many NodeRevision rows are kept per node in this

    memory. On each new revision the oldest overflow is pruned. Must be >= 1 (chk_memory_max_rev_count_positive); default 10.

  • kdf_salt

    Spec 041 (D-2026-07-06-B) — passphrase-derivation material for a caller-held-key encrypted memory. Parameters, NOT secrets: salt (base64) + scrypt params. NULL when the memory was encrypted with a raw data key (no passphrase) or is not encrypted.

  • kdf_params:
  • key_verifier

    enc:v1 encryption of a fixed check string under the data key — lets every unlock verify the supplied key WITHOUT touching node rows (wrong passphrase = typed WRONG_KEY, never garbage plaintext). The server still never holds the key itself.

  • vector_index_encrypted_ack_at

    Timestamp the owner acknowledged the embedding-inversion disclosure for an ENCRYPTED memory (FR-026). NULL ⇒ not acknowledged. Gates encrypted-memory indexing via chk_memory_vector_encrypted_ack.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • urn_normalized_at

    Online URN-shape migration gate (spec 021 FR-032, repurposed for the #697 v1→v2 emission flip). Null = pre-normalization row; set = row normalized onto the flat v2 form (<root>:<slug>, single colon). Transient. TODO(spec-021-cleanup): drop once the FR-032 migration completes.

  • urn_migration_failed_reason

    Spec 021 sentinel for data-defect rows during the FR-032 migration. TODO(spec-021-cleanup): drop alongside urnNormalizedAt.

  • legacy_urn

    697 stored alias map: the pre-v2 (v1) URN this row was migrated FROM.

    Null until the online migration flips urn to the flat v2 form; then a legacy input (wikilink, export, external link) resolves to this row by matching legacyUrn. Indexed, non-unique — resolution disambiguates a rare collision to the live row, else a typed error. Transient with the migration; TODO(#697-cleanup): drop once every reference is v2-native.

assets

A user-uploaded file (document, image) bound to a Memory. Bytes live in object storage (Cloudflare R2 in v1; MinIO for local dev); this row carries metadata, the storage pointer, and virus-scan state. Spec: hadron-concept/spec-kits/specs/004-asset-upload/spec.md (sister repo).

Why a separate table (not a nodeType): normalization (asset and node schemas diverge), scale (raw-material assets shouldn't bloat the knowledge-node table), and FK-shape (containment is foreign-key-shaped, not graph-shaped). See hadron-concept/design-discussions/hadron-platform/2026-04-28-asset-upload-design/010-summary.md (sister repo) §"Why this summary supersedes 007-summary.md".

URN form (computed, NOT stored): grammar v2 hrn:asset:<root>:<mem...>:assets:<asset.id>, emitted by emitAssetUrnV2 from the holding memory's stored bare urn. The GraphQL Asset.urn docstring carries the full contract, including the two degraded shapes a parser has to tolerate and why <mem...> is not always a single atom.

Cross-references from nodes are reserved for a future spec — Node.attachedAssetId? (one-asset case) or a node_assets join (many-to-many). Not in v1.

Properties as follows:

  • id:
  • memory_id

    The Memory this asset belongs to; NULL while the asset is staged (uploaded but not yet attached). Janitor sweeps staged assets past the 24h TTL.

  • filename

    Original filename as supplied by the user. Never appears in storageKey.

  • mime_type: RFC 6838 type/subtype.
  • size_bytes: Verified at complete-upload time against HeadObject.contentLength.
  • storage_key

    Object-store key shape: {orgUrn}/{memoryUrn-segment}/{assetId}.{ext}. Encrypted at rest when the memory is encrypted; plaintext otherwise.

  • scan_status: Virus scan state. Downloads gated on CLEAN.
  • scan_signature

    Engine signature name recorded when the scan verdict was BLOCKED (e.g. "Eicar-Signature"). A BLOCKED row is kept as an audit tombstone; its object bytes are deleted (#896).

  • scan_attempts

    Number of scan attempts so far (inline at complete-upload plus sweep retries). Drives the retry sweep's exponential backoff.

  • scanned_at

    When the last scan attempt ran (whether or not it produced a verdict). NULL = never attempted. Informational; the sweep selects on scan_due_at, not this.

  • scan_due_at

    When the next background scan action is due (the #882 embedding-queue pattern: a future-dated stamp IS the queue). PENDING rows: next scan retry. BLOCKED rows: next purge retry for object bytes that survived a failed delete. NULL = nothing pending (CLEAN, or BLOCKED with bytes confirmed gone). Every sweep touch pushes it forward, so no row can monopolize a batch.

  • bytes_checked_at

    When the bytes-missing row sweep (#1140) last examined this row. NULL = never. It is the sweep's persisted cursor (least-recently examined first, NULLs first), so a restart resumes instead of re-walking the same head of the table. A deferral (encrypted memory with no cached session key) stamps it too, so such a row rotates behind other work; a failed store lookup does NOT.

  • description: Optional; agent- or user-provided.
  • uploaded_at:
  • uploaded_by

    fk to User.id — who uploaded. NULL when the asset was created server-side by an app run with no on-behalf-of user (hadron_store_file); the run id is recorded on the asset's reference node and in the audit log.

  • deleted_at

    Soft-delete marker. Janitor sweeps R2 object + hard-deletes after 24h.

  • public_link_enabled

    1667, cor:dmo:060:15 — the per-asset public-link opt-in. STORED POLICY, not

    proof of publication: the anonymous hotlink also needs the deployment gate and the existing eligibility checks. Every asset starts OFF.

nodes

Properties as follows:

  • id

    UUIDv7 from node.yaml when supplied by the importer (stable across moves); falls back to cuid() for inserts that omit id.

  • memory_id:
  • node_type: See the node-types list in the model doc. Default info.
  • object_type

    725 — collection discriminator (the MongoDB-collection equivalent): which

    domain object this node is an instance of, e.g. "competitor" / "insight". Orthogonal to nodeType (the platform-kind axis). NULL for an ordinary node. When set on a schema-governed memory it must name a declared object type (enforced at write time — a later phase); free-form until then.

  • name: Human-friendly display name of this node.
  • alias: Alternative name.
  • loc: Colon-delimited path within the memory (e.g. "auth:tokens").
  • is_link:
  • is_placeholder

    1450 — a RESERVED spec citation with no spec written yet (a placeholder

    in a draft corpus; see src/lib/specCorpus.ts). Set only by the server's reserveSpecCitation, never by a client write, and never inferred from an empty body. Writing real content clears it; the node keeps its citation. Minting refuses while any remain, so a minted corpus has none.

  • description:
  • abstract

    Paragraph-length summary of this node. Cap is 2000 characters, enforced at the API boundary (not as a DB CHECK — caps are validation, not invariants). Surfacing rules across MCP tools (find/read/list/validate), the Source: abstract-fallback marker on hadron_get_node content-scope fallback, and the RAG-substrate motivation are documented in spec 031 (FR-005 + edge cases). That is the load-bearing reference; this comment is the cold-read pointer for someone scanning the schema.

  • content: The topic content (topic.md full text).
  • content_hash

    SHA256(yaml+md)[0:8] for change detection. Set by external producers (YAML frontmatter via importer, Git sync). UNCHANGED by spec 032 — that spec adds abstractOriginHash below as a separate column with its own domain (SHA256(content)[0:8]); the two are never compared against each other.

  • abstract_origin_hash

    Spec 032 — fingerprint of content value at the time abstract was authored. SHA-256 of plaintext content truncated to 8 hex chars (same width as contentHash, different domain). At read time, compared against computeContentHash(node.content) to detect staleness: the abstract may not reflect current content when the two differ, OR when this is NULL on a node that has both an abstract and content (#1128 — an abstract written before the body existed was never fingerprinted, so it has never been checked against it; that reads as unverified, not as verified). NULL is a clean state only when the node has no abstract, or no content for the abstract to describe. Surfaced by hadron_get_node's Source: abstract-stale marker and hadron_validate's [stale-abstract] warning. System-managed: never settable via GraphQL NodeInput.

    Until #1232 this said staleness required the value to be NON-NULL — the pre-#1128 rule, which #1128 deliberately removed along with the validator's own != null guard. The published Data Model reference is generated from this comment, so it contradicted the GraphQL reference for the whole gap.

  • embedding_pending_at

    Set when this node needs (re-)embedding; cleared on success. The single work signal the embedding worker drains (FR-006/FR-007). Operational state only — intentionally NOT versioned on NodeRevision.

  • embedding_work_token

    internal#4: opaque identity of one durable obligation; time only schedules it. Operational, never copied into revisions or approval/authorship state.

  • embedding_failed_at

    Set when an embed attempt failed (record, not a work signal). Transient failures keep pending set for retry; permanent failures clear pending (FR-009).

  • embedding_attempts: Attempt counter for backoff / give-up. Non-null; reset to 0 on success/revoke.
  • embedding_truncated_chunks: Passage chunks omitted by the per-node cap (#887); NULL when not truncated.
  • embedding_error: Last embed error (diagnosability; surfaced by hadron_validate).
  • tokens: Number of input tokens.
  • tags: Classification tags.
  • properties: Typed key-value structured data; queryable via the API.
  • data

    Structured JSON on the node; used for template-variable resolution, user profiles, extracted facts, reference metadata. Returned by hadron_get_node; written by hadron_update_node (replaces the bag) or hadron_update_node_data (shallow merge).

  • seq

    Sort order among sibling nodes (lower values come first); used by hadron_get_next_node and portal drag-and-drop reordering.

  • message_channel_id

    1430 paged attention: the owning Channel for chat-message transcript

    rows — stamped in the append transaction, providing a Channel-local seq-first access path (see the partial index below).

  • owner_repo: GitHub repo slug (e.g. "micromentor/mmdata").
  • is_runnable: If true, this node can be executed as a task.
  • role

    1201 — what this node IS TO ITS AUTHOR, as an open string. Set it to

    anything; the platform reads a small CLOSED subset and ignores the rest.

    THREE KIND-ISH FIELDS, and the distinction is what readers get wrong: - nodeType — the PLATFORM-kind axis (info/task/prompt/…), load-bearing for retrieval and rendering. NOT this field. - objectType — the COLLECTION discriminator (#725): which domain object this is an instance of, schema-validated. NOT this field. - role — what the node is FOR. It does not affect default retrieval/ranking, but callers may filter by role family.

    This is the axis the law corpus already named and the schema never had: cor:urn:010:01 lists node TYPES and node ROLES as separate categories, and the roles (chat, chat-message, config, …) live in nodeType today. Migrating those off nodeType is deliberately NOT part of #1201 — live consumers include isChecklistItemListing, the chat surfaces and preflight_add --type.

    GOVERNED values (src/lib/governedRole.ts) route a write to that kind's own door; every other value is inert. Open so an agent builder may use it freely, closed where it gates so the gate is never caller-defined.

  • llm_model

    LLM model that created or last modified this node (e.g. "claude-opus-4-6", "gpt-4o").

  • ai_agent

    AI agent tool that created or last modified this node (e.g. "claude-code", "cursor", "hadron-portal").

  • authorship_kind

    1326 — server-owned attribution for this content state. A task stamp

    records the stable task Node.id and its revision when the content was authored; a HUMAN stamp records the authenticated person, never a task. NULL kind means unknown/legacy, not a claim of human authorship. No FK: deleting or moving a task/user must not rewrite historical attribution.

  • authored_by_task:
  • authored_by_revision:
  • authored_by_human:
  • authored_at:
  • rev_seq

    696/#1323: the live node's current revision. Creation is revision 1.

    A revisioned edit snapshots the pre-edit state at this number, then atomically advances the live row to the next number.

  • content_rev_seq

    1611 (cor:dmo:120:04) — the revision at which the approval-hashed fields

    (title, abstract, content under approval-hash v1) last changed through a SANCTIONED writer; maintained by the nodes_initialize_revision_content_hash trigger on the same 'refresh' marker as revisionContentHash. An approval recorded at approvedRevNo is still valid iff contentRevSeq <= approvedRevNo: metadata-only revisions advance revSeq but not this. A write outside the revision system never moves it, so such a change stays TAMPERED.

  • revision_content_hash

    1323: host-independent MD5 of the complete at-rest revisioned state.

    Internal safeguard only (never an artifact fingerprint): an exposed read reconciles a mismatch by taking a server-authored revision. Included partials/template data and operational fields are deliberately outside it.

  • approved_rev_no

    1591 — the node's LATEST approval, kept here rather than only on a

    NodeRevision row because the live revision has no row (rows are pre-edit snapshots) and rows are prunable and deletable. The current revision is approved iff approvedRevNo >= contentRevSeq (#1611); a lower number means its content changed since. approvedBy is a User.id when one is known, with no FK so a user deletion cannot rewrite who approved; otherwise approvedByInfo holds the principal (the NodeRevision.editedByInfo convention). approvalHash is the full SHA-256 of approval hash v1 (src/lib/approvalHash.ts) at approval time. All five are set together or not at all (chk_node_approval_complete), except that approvalHash alone is cleared when the node enters an encrypted memory (#1838): who, when and which revision stay, and a hashless approval covers nothing.

  • approved_by:
  • approved_by_info:
  • approved_at:
  • approval_hash:
  • minted_at

    1591 — per-node minting. A node is minted iff mintedAt is set; a new

    node starts unminted, with draft rights (renumber, move without an alias, bulk replace). Minting stamps every unminted live node of a memory at once (mintMemoryNodes), after its checks, including an approved current revision. mintedRevNo / mintedHash record that revision and its approval hash; both are null for nodes backfilled as minted by the #1591 migration, whose minted revision is unknown. mintedBy is a User.id (no FK, like approvedBy), else mintedByInfo holds the principal ("backfill" for the migration). Minting protects nothing by itself (Holger, 2026-10-01: no minted-spec permanence for now). chk_node_mint_complete.

  • minted_by:
  • minted_by_info:
  • minted_rev_no:
  • minted_hash:
  • content_changed_at

    1632 / cor:dmo:130:04 — when the node's title, abstract or content last

    changed, from the DB clock. Set only by the signing trigger (prisma/signing-invariants.sql), never by application code, and never decreases. A signature verified at or before this time reads EARLIER, so restoring earlier text never revives it (#9824). Null = unchanged since creation. A timestamp rather than a revision number, so pruning, history clears and revSeq reconciliation cannot move it.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • created_by_worker_id

    1610 — the Worker / Agent behind the write, beside the user in

    createdBy / updatedBy. Server-derived from the request's validated session binding or App run (src/lib/requestActor.ts), never client-supplied; stamped centrally on creates and authored-field updates (src/integrations/db/client.ts). The updatedBy* pair describes the LAST authored edit, so an edit with no agent behind it clears it. No FK, like the audit stamps (cor:dmo:010:01).

  • created_by_agent_id:
  • updated_by_worker_id:
  • updated_by_agent_id:
  • updated_by_user_id

    2176 — the User behind the last authored edit, beside the Worker / Agent

    above and stamped with them in one place (src/integrations/db/client.ts). It is exactly what NodeRevision.editedBy records for the same edit (editorFromAuth): the request's validated auth.userId, from the RequestActor holder, never a clientId or a credential holder. An authored edit with no user behind it clears it. Null = unknown (nodes edited before

    2176 are not backfilled). No FK, like the audit stamps (cor:dmo:010:01).

node_embeddings

033-rag-vector-retrieval: a stored embedding vector for a node's abstract or one of its content chunks. Vectors are computed on plaintext at write time (FR-027) and stored plaintext (pgvector). The embedding column is Unsupported("vector(768)") — Prisma has no native vector type, so it is NEVER read/written through the generated client; all access is raw SQL ($queryRaw/$executeRaw). The HNSW index + abstract partial-unique index live in the migration + post-push.sql (not expressible in Prisma schema).

Properties as follows:

  • id:
  • node_id:
  • memory_id

    Denormalized for fast per-memory similarity filtering (search filters by memory before ORDER BY distance).

  • kind:
  • provider: Embedding provider — "local" | "openai" | "voyage" … v1 is always "local".
  • model

    Stored model id (FR-014) — e.g. "nomic-embed-text-v1.5". Forward-compat for a deliberate re-embed when the platform model changes.

  • dim: Vector dimension (sanity / forward-compat guard).
  • chunk_index:
  • char_start:
  • char_end:
  • chunk_text:
  • created_at:

edges

Directed edge between two Nodes. The optional name describes the relationship — e.g. "imports", "depends_on", "related-to", "cites", "abstract-of". An edge whose target is not yet synced lives in PendingEdge until the target arrives. A directed Node→Node relation, upgraded to a first-class, addressable entity (it has its own URN hrn:edge:<root>:<memory>:<loc>). Edges drive task execution/automation and the chatbot/conversation platform, not just describe graph relationships.

Properties as follows:

  • id:
  • memory_id

    Denormalized from the SOURCE node's memory so loc can be made unique within a memory (a unique index can't span the source-node table). For cross-memory edges this is the source's memory.

  • source_id:
  • target_id:
  • loc

    Colon-delimited path within the memory — the edge's identity and the suffix of its URN (hrn:edge:<root>:<memory>:<loc>). Required; derived from the endpoints + name when not authored (see src/lib/edgeLoc.ts). Mirrors Node.loc.

  • name

    Free-form relationship name (e.g. imports, depends_on, abstract-of). Optional since spec-037 — loc is now the identity. (Was label.)

  • description: Human-readable description of the edge (parity with Node.description).
  • is_runnable

    If true, this edge can be executed/run (task automation, conversation transitions). Mirrors Node.isRunnable.

  • condition

    JSONLogic gating expression evaluated by the shared edge-condition evaluator at edge-resolution time. NULL means the edge always fires. Validated against the v1 operator subset and the FOUR variable scopes (memory.*, chat.*, agent.*, message.data.* — VALID_SCOPE_PREFIXES; anything else is UNKNOWN_SCOPE). The time builtins now() and today() are a SEPARATE constant, not a fifth scope: whole references rather than prefixes, pre-resolved by the evaluator from the request clock. Said "five variable scopes" here until #1246, in the same sentence as the GraphQL SDL and generated into the public Data Model reference. Spec: hadron-concept/spec-kits/specs/001-edge-condition-spec/spec.md (sister repo). User docs: https://docs.hadronmemory.com/reference/edge-conditions/.

  • priority

    Resolution-order hook for edges sharing a source node; lower fires first, ties broken by insertion order. Reserved space for the future agent-exceptions feature to slot handler edges at the top.

  • data

    Free-form structured payload on the edge (e.g. transition metadata for conversation-design edges).

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • governed_kind

    1606 (cor:dmo:110:01) — set only by the comment path: the edge is a

    comment's anchor (comment → target) or reply (reply → thread root). NULL for every ordinary edge. A governed edge is immutable (DB trigger edges_governed_immutable) and no generic edge write may create, alter or delete one (cor:dmo:110:04).

  • anchor_rev_no

    The target revision a top-level comment was written against. Set iff governedKind = COMMENT_ANCHOR (CHECK chk_edges_governed_anchor).

  • anchor_approval_hash

    computeApprovalHash of the target's title/abstract/content AT anchorRevNo (64 lowercase hex), whether or not that revision was ever approved, so the anchored text stays checkable after the revision snapshot is pruned (cor:dmo:110:01).

comment_meta

1606 — the comment-specific state of a nodeType = 'comment' node, 1:1.

The body is the node's content; the quote and moderation reasons live in the node's data, so an encrypted memory encrypts them with the body. The columns here are what a constraint or an index must see in plaintext.

Invariants (prisma/post-push.sql + migration 20261005200000_comment_nodes): meta ⇔ comment type; comment, target and thread root share one memory of a commentable class; a target is never a comment; targetNodeId, threadRootId and authorKey are immutable and equal the governed edges' endpoints; at most one open, live top-level thread per (target, author) (comment_meta_one_open_thread, a partial unique index Prisma can't model).

Properties as follows:

  • node_id:
  • target_node_id

    The commented node. Immutable. ON DELETE CASCADE only so a whole-memory delete never depends on cascade order: hard-deleting a commented target on its own is still refused, by the governed-edge trigger (its anchor edge cannot go while the comment exists) and, at commit, by the comment-without-meta check.

  • thread_root_id: NULL for a top-level comment; else the thread's top-level comment.
  • thread_state: OPEN | RESOLVED for a top-level comment; NULL for a reply (CHECK).
  • author_key

    The author (cor:dmo:110:03): w:<workerId>, ua:<userId>:<agentId>, u:<userId> or app:<appId>. Immutable.

  • retracted_at

    1721 — set when deleteComment leaves a stub (a top-level comment with

    live replies; its text is blanked). A comment deleted without replies is soft-deleted instead, and these record who deleted it.

  • retracted_by: Actor key (the authorKey grammar) of whoever deleted the comment.
  • resolved_at:
  • resolved_by:
  • thread_deleted_at

    Mirrors the comment node's soft delete (a thread delete, or the target's soft delete), so the one-open-thread index can exclude it.

  • thread_deleted_by:
  • thread_deleted_cause

    ADMIN (deleteCommentThread), AUTHOR or MANAGER (#1721 deleteComment, by its author or by a memory manager), or TARGET (the target was soft-deleted; restoring the target restores exactly these).

  • created_at:

pending_edges

An edge whose target Node has not been synced yet; stored without a foreign key to the target. When the target Node is synced, the PendingEdge is converted to a regular Edge.

Properties as follows:

  • id:
  • source_id:
  • target_id

    Intended target node id — NOT a foreign key; resolved at promotion time.

  • loc

    Edge loc carried so an authored loc survives until promotion; the promoted Edge derives one when this is null. (Mirrors Edge.loc.)

  • name: Free-form relationship name (was label).
  • description: Preserved until the unresolved edge is promoted; empty differs from null.
  • data: Structured edge payload carried through deferred Git sync and cloning.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

sessions

Properties as follows:

  • id:
  • type:
  • app_id:
  • user_id

    The User this session is attributed to (typically the end-user in a chatbot/automation session; the developer in a DEVELOPER session).

  • agent_id

    The Agent driving the session (NULL for free-form developer sessions not tied to a specific Agent). When workerId is set this records the ROLE-agent behind the casting (cor:agt:020:03).

  • worker_id

    974 — the named identity doing the work: the Worker (casting) this

    session is bound to (cor:dmo:050:11, cor:agt:020:03). Binding is gated at start (the worker must belong to the session's App); "taken right now" derives from an ACTIVE session bound to the worker.

  • role

    2458 (cor:dmo:050:11): the worker's role AT BIND, stamped from the locked worker row with agentId, so a

    past session keeps the role it ran under after the worker's agent (and so its role) changes. Null for a session with no worker; the migration backfills earlier sessions exactly (the role was immutable before #2458).

  • memory_id

    The active write-memory for this session, when there's an unambiguous one. Resolves the multi-writable-memory ambiguity.

  • expires_at

    Hard expiry; the session reaper (src/jobs/reapSessions.ts, #930) ends sessions past this point. Since #1114 this is the ONLY thing the reaper acts on: a NULL here means the session is never ended automatically at all, because inactivity stopped being a reason to end one. It still stops reading as LIVE once nobody drives it inside its idle window, but that is derived at read time (lib/sessionActivity.ts) and mutates nothing. Set by startAgentSession from the App's sessionTimeoutSeconds — a promise made at session start rather than an inference from silence; startSession deliberately leaves it null (the client contract carries no TTL), so an explicit endSession is what closes those.

  • repo: Git repo slug.
  • branch: Git branch name at session start.
  • pr_number: GitHub PR number.
  • customer_id: Tenant/customer identifier (free-form, supplied by the App).
  • language: Spoken ("en", "es") or programming language.
  • plan: The execution plan, when one was prepared.
  • llm_model: LLM model used (e.g. "claude-opus-4-6").
  • transcript_path

    928 coding-session provenance: where the driving tool's transcript

    physically lives on host (a filesystem path in that tool's store).

  • host: #928: machine identifier the session ran on.
  • tool: #928: the tool driving the session ("claude-code", "codex", ...).
  • family

    1707 — the model family this session runs as (cor:agt:060:04): given

    at session start, or derived from llmModel then tool; null when it could not be classified. A worker's family is its live bound session's. A matching input only, never an authorization input: it is self-declared.

  • model_reported_at

    2252 — when llmModel was last SELF-REPORTED (start, resume, or an

    updateSession carrying a model; a repeat of the same model counts). Null for a session that never reported, including every row from before this column: no historical backfill. Not updated_at, which unrelated writes move. Describes a self-report, not verified detection.

  • launch_host_id

    1709 (cor:agt:070:08; Holger via Vera #10773) — a host-launched session:

    the host that started it, the worker.start operation, the task it was launched for (none for a manager's start without one), and who issued the start (platform | manager). Bound on the holder's own token; the hold is unchanged. All four null for a session a person started by hand.

  • launch_operation_id:
  • launch_task_id:
  • launch_issued_by:
  • input_tokens: Total prompt tokens across the session.
  • output_tokens: Total completion tokens across the session.
  • turn_count: Number of human-AI exchanges.
  • error_count: Failed tool calls / action runs.
  • parent_session_id: Sub-agent vertical relation (this session was spawned by a parent).
  • prev_session_id

    Chain horizontal relation (linked journey — this session continues from a previous one).

  • summary: AI-composed summary at session end.
  • outcome: 0.0-1.0, reported externally.
  • outcome_ref: GUID or URL of authoritative outcome record.
  • outcome_meta: Domain-specific outcome detail.
  • started_at:
  • ended_at:
  • end_reason: First end wins. NULL on legacy ended rows is exposed as unknown, never backfilled.
  • auto_expired_at

    Set by the reaper (#930) when the session was auto-expired — meaning past expiresAt, and since #1114 nothing else. It no longer records an idle-window expiry, because there is no longer such a thing: inactivity never ends a session. Rows carrying this from before that change are the only ones stamped for idleness, which is why the liveness derivation still drops updatedAt on an auto-expired row (the reap overwrote it). Always written together with endedAt and to the same instant, so "ended" stays the single predicate endedAt IS NOT NULL and this column records only HOW it ended. (#1232 — this read IS NULL, which is the predicate for a session that has NOT ended, and it said so in the published Data Model reference.)

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

usage_events

Record of a single operation within a Session (read, write, action run, edge traversal, session summary).

Column type is String (not enum) — intended values: read | write | action-run | edge-traversal | session-summary. Tightening to a Prisma enum is reserved for a future cleanup spec.

Properties as follows:

  • id:
  • type:
  • node_loc: Stored directly so the event survives node deletion.
  • node_id: Set null on node deletion.
  • memory_id

    Memory the event is attributed to (#796). Stored DIRECTLY at write time like nodeLoc — deliberately NO relation, unlike this model's five other FKs. Those are all SetNull, and memory-scoped analytics used to reach the memory by joining through node, so deleting a node silently erased the event from its memory's history. A SetNull FK here would recreate that loss one level up (on memory deletion), which is exactly what this column exists to prevent.

  • session_id: Set null on session deletion.
  • app_id: The App that authored this event.
  • action_args: Key-value args when type = 'action-run'.
  • model: LLM model used for this specific event.
  • tokens_in: Input tokens consumed.
  • tokens_out: Output tokens generated.
  • user_id

    The on-behalf-of user (billing attribution). Nullable — pure-App service runs have no user. Distinct from the audit createdBy string.

  • organization_id

    The billable organization. Set on every metered event so ledger attribution never needs a join through App.

  • provider

    LLM provider that served the call — model alone is ambiguous across providers (e.g. claude via anthropic vs bedrock).

  • key_owner_type

    AiConfigOwnerType of the API key that served the call (HADRON_SERVER | ORGANIZATION | APP | AGENT). Only HADRON_SERVER spend is platform-paid and thus debitable; BYOK is observability-only.

  • cost_micro_cents

    Provider cost snapshot in micro-cents (1e-8 USD), computed from the AiModelPrice row effective at event time. NULL = no price known (or the event carries no tokens). Never recomputed — prices change (FR-003).

  • counts_as_activity

    1653 / ruling DY-2: whether this event counts as ACTIVITY for its

    session's liveness. True only when the session was live AND owned by the recording principal at write time (usageEventCountsAsActivity), so a request attributed to a LAPSED session keeps its attribution but never revives it — resuming is the DA door alone. Defaults to false so a writer that forgets the check fails safe; rows before the column are backfilled true by the migration, so liveness was unchanged at deploy.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

agents

The Agent definition — what a Builder creates and what the marketplace sells. One Agent row holds the canonical conversation design (system memory), the default AI config, the declared memory-provisioning policy, and the declared installation policy. Spec: 008-agent-installation (2026-05-02).

An App is the deployment of an Agent in some org. The Agent is what is shared across installations; the App is what authenticates, holds members, and accumulates per-deployment data. (PWA analogy: you build an Agent, and when someone installs it, the running instance is called an App.)

Examples: "Mealplan" (the Agent your family meal planner is built from), "Juno" (the mentee chat agent shared across MicroMentor orgs).

Properties as follows:

  • id:
  • uses_tasks

    2138 §3.5 — false: every worker cast from this Agent counts as HAVING a task (coordinators, the

    lifecycle agent), so it is expected to check every period.

  • reset_context_after_task

    2162 (cor:agt:050:27) — when a task one of this Agent's workers had started finishes or is cancelled, and it holds

    no other started task, the platform asks the worker's host to reset its context: a shed, never a session end. Off by default; written by whoever manages the Agent, like usesTasks.

  • organization_id:
  • owner_user_id

    User owner of a user-owned Agent (rooted on the bare <handle> — #697 v2, no @ sigil). The org/owner XOR is ENFORCED — chk_agent_owner_xor in post-push.sql: (organization_id IS NULL) <> (owner_user_id IS NULL) — so exactly one of organizationId/ownerUserId is non-null.

  • urn

    Globally unique identifier (e.g. "micromentor.org:juno"); derived from org.urn + ":" + slug.

  • name: Display name of this agent.
  • description:
  • boot_prompt_node_id

    2045 (S8, cor:agt:040:07) — this Agent's boot-prompt POINTER: the id of a

    compiled boot-prompt node (nodeType = 'compiled-boot-prompt'), never its source. NO foreign key: nodes are hard-deleted on some paths (deleteNode hard/subtree, memory merge, git-sync cleanup), and SET NULL would turn a deleted target (R27) into "no pointer" (R26) while RESTRICT would block those deletes. bootPromptUrn is the target's canonical URN at write time, read only when the row is gone; both are set or both NULL (chk_*_boot_prompt_pointer_pair, prisma/boot-prompt-pointer-invariants.sql). Written only through setBootPromptPointer (src/lib/bootPromptPointer.ts).

  • boot_prompt_urn:
  • system_memory_id

    Memory containing conversation designs (stages, prompts, partials). Universally read-only from any App context post-008 (DEVELOP-from-App is dropped per R-10); edits happen in the Agent ownership surface.

  • visibility

    PUBLIC | ORGANIZATION | PERSONAL (035-visibility-enum-cleanup gave agents their own enum). PERSONAL is the creator-only draft state.

  • listed_on_marketplace

    Opt-in marketplace catalogue flag (cor:acl:080:04): whether this agent is advertised in the marketplace browse. DISTINCT from visibility — PUBLIC governs access, this governs advertisement. Contributes to the owner org's discoverability (cor:acl:080:02) only when that org is activated.

  • type

    Coarse behavior hint — see AgentType enum doc. Largely legacy post-008.

  • surfaces

    Surfaces this Agent is designed for (free-form per 008 R-9; v1 known values: 'chat', 'slack', 'mcp', 'web'). Distinct from the per-App surfaces — this is the design-time declaration.

  • published_revision_loc

    Loc of the currently-published revision of the Agent's system memory. Lets the Builder ship draft revisions without affecting running Apps.

  • editor_lock_user_id

    Optimistic editor-lock owner (one Builder at a time can hold the edit lock on the system memory).

  • editor_lock_expires_at: When the editor lock expires (auto-released on stale).
  • properties

    Agent working state (per-user data like family budget, preferences); automatically available to the LLM as context.

  • memory_provisioning

    Declares how this Agent expects per-App memory to be provisioned. Shape: { appMemory: 'shared' | 'user' | 'none' }. personalMemory provisioning is implicit (lazy-create on first user-attributed write). 008-agent-installation FR-008.

  • register_defaults

    Spec 049 Phase 5 (plan §3.5 recommendation): the defaults this Agent's install-created register row is made with — { mentionOnly?: boolean }. A scalar default, not a reference that can rot; null = platform defaults.

  • installation_policy

    Declares membership constraints for any App that installs this Agent. Shape: { maxMembers: number | 'unlimited', memberRoles: string[] }. maxMembers enforced at AppMember invite-acceptance time. 008-agent-installation FR-009.

  • persona_role

    Persona role — free string with conventions ("backend-engineer"). A dedicated column so roster/casting queries can filter without parsing the prompt.

  • extends_agent_id

    1885 (cor:dmo:050:14) — the one base Agent this Agent extends, or null.

    The child inherits its base chain's system-memory nodes (except boot prompts). One base, no cycles, at most 4 Agents in a chain counting this one: enforced by src/lib/agentBase.ts, the only writer, and backstopped by agent_base_guard (prisma/agent-base-invariants.sql). Restrict, as for an imported Agent: a live child keeps its base from being removed.

  • cloned_from_agent_ref

    1892 (cor:dmo:050:15) — the index node whose incoming, trigger-labelled

    edges list this Agent's own tasks; null when it names none. Written only by setAgentIndexRefs, read by src/lib/agentDefinitionLists.ts. SetNull: removing the index node unsets the pointer.

    2245 (R145/R146): the Agent this one was cloned from, as a plain ref (the source's URN at clone time).

    No FK: the source may be retired or renamed, and the provenance must survive both.

  • tasks_index_ref:
  • processes_index_ref

    1892 (cor:dmo:050:16) — the index node whose incoming, trigger-labelled

    edges list the processes this Agent starts or owns; null when none.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • urn_normalized_at

    Online URN-shape migration gate (spec 021 FR-032, repurposed for the #697 v1→v2 emission flip). Null = pre-normalization row; set = row normalized onto the flat v2 form (<root>:<slug>, single colon). Transient. TODO(spec-021-cleanup): drop once the FR-032 migration completes.

  • urn_migration_failed_reason

    Spec 021 sentinel for data-defect rows during the FR-032 migration. TODO(spec-021-cleanup): drop alongside urnNormalizedAt.

  • legacy_urn

    697 stored alias map: the pre-v2 (v1) URN this row was migrated FROM

    (see Memory.legacyUrn). Null until the online migration flips urn to v2.

agent_memory_items

Associates a Memory with an Agent, with a per-memory access level. The Agent controls which memories are read-only vs read-write per-attached-memory. After 005-agent-subscription, AgentMemoryItem.role is the sole per-knowledge-memory write cap (the AppAgent-level cap was first relaxed in 005, then the AppAgent join itself was dropped in 008-agent-installation).

Properties as follows:

  • id:
  • agent_id:
  • memory_id:
  • role

    "read" or "read-write". Default "read". Controls whether the Agent can write to this memory.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

memory_licenses

Commercial usage grant of a Memory; defines capacity and terms. Consumed via MemorySubscription.licenseId.

Properties as follows:

  • id:
  • memory_id:
  • license_type

    Column type is String (not enum) — intended values: user | app | organization.

  • seats: Number of consumers allowed to use this license.
  • valid_from:
  • valid_until:
  • license_keys: One or more license keys.
  • terms: Usage terms & conditions.
  • activated

    If true, the memory will be merged into the blended graph for the consumer.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

memory_subscriptions

An Organization subscribes to another Organization's Memory. Governed by a MemoryLicense when the memory requires one.

Access evaluation order (cross-org chain — extended in 005-agent-subscription with the App↔Agent and User↔Agent gates; 008-agent-installation added AgentOrgGrant; 023-app-shape replaced the direct App.agentId with the AppAgent join (an App can install N Agents)): 1. App ↔ Agent — the App has the Agent installed (an AppAgent row links them) AND Agent.visibility allows the App's org. Cross-org installs (App.organizationId != Agent.organizationId) additionally require an active AgentOrgGrant(App.organizationId, agentId). Same-org installs auto-pass. 2. Agent ↔ Memory (knowledge / app / system) — current implementation (src/mcp/access-control.ts#foldAgentIntoAccessMap): AgentMemoryItem(agent, memory) exists OR memory is the Agent's systemMemoryId. When cross-org for knowledge: MemorySubscription(orgB, memory) AND any required MemoryLicense valid (not expired, seats available). Known gap (tracked in issue #115): this gate does NOT auto-grant access to app-class memories where memory.appId = App.id AND memory.class = 'app'. Today an explicit AgentMemoryItem row is required for app-class memories to be reachable through the MCP/GraphQL gates. The spec called for auto-grant; the implementation currently does not. 3. User ↔ Agent (personal-class memory only) — AgentSubscription(user, agentId) exists AND active per the predicate, AND Memory.appId = App.id (the per-App isolation that User Story 2 hangs on — a session through App A cannot read the personal memory at (B.id, user.id) for some other App B of the same Agent). 4. Effective role — most restrictive of AgentMemoryItem.role and MemorySubscription.role. (The legacy AppAgent.role is dropped post-008 — system memory is universally read-only from any App.) personal/private-class memories enforce strict ownership additionally: even an ADMIN/OWNER who would otherwise satisfy gate 2 cannot read a personal/private memory they do not own (FR-016).

Worked example (the four-org Juno scenario, 008 vocabulary): an App in OrgA deploys Juno (Agent in OrgB with visibility=ORGANIZATION since Alice is a Micromentor org-member; or PUBLIC for marketplace shape) which references a knowledge Memory in OrgC. The cross-org App↔Agent gate is satisfied by an active AgentOrgGrant(OrgA, juno). End-user Alice (personal org personal-alice) chats through that App; her records land in a personal Memory at (App.id, alice.id) (Memory.userId = alice, Memory.appId = App.id, class = personal, visibility = null). The cross-org write into Alice's personal memory is granted by AgentSubscription(alice, juno) — without it, Juno has zero access. If Alice installs Juno into a second App (different Org), her records there go to a separate (B.id, alice.id) row — fully isolated from the OrgA installation. Each gate above must clear in order; failure denies at the right layer with a typed error.

Properties as follows:

  • id:
  • memory_id:
  • organization_id: The subscribing organization (not the owner).
  • license_id:
  • role

    Column type is the full Role enum, but the intended grant set is CONTRIBUTOR | READER (reader = read-only, contributor = read-write). Tightening reserved for a future cleanup spec.

  • activated

    If true, the memory will be merged into the blended graph for the subscriber.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

hadron_server

Represents a running Hadron server instance (SaaS or self-hosted). Each organization connects to one server; a server serves one or many organizations.

Properties as follows:

  • id:
  • organization_id

    The organization that owns/operates this server; NULL for the Baragaun SaaS server.

  • url: Base URL of this server (e.g. "https://server.hadrongraph.io").
  • log_level: Minimum level for ServerLogEntry records.
  • version: Deployed software version.
  • last_heartbeat_at: Last health-check timestamp.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

ai_service_configs

Named AI service configuration (spec 036). Owned by exactly one of HadronServer / Organization / App / Agent — enforced by the Postgres CHECK chk_ai_service_config_owner (see prisma/post-push.sql; Prisma cannot express it). Resolved by name walking App -> Agent -> Org (of the App, else of the Agent) -> HadronServer; the first ENABLED config with the requested name wins. Well-known fallback name: 'default' (conventional extras: 'fast', 'frontier'). Name is unique per owner via four partial unique indexes (also post-push.sql). Replaces the legacy Agent.ai_* / App.ai_* columns, which the 036 migration dropped without backfill (stored values confirmed disposable 2026-06-11).

Properties as follows:

  • id:
  • name: Lookup name used by the resolution walk; lower-case canonical.
  • hadron_server_id:
  • organization_id:
  • app_id:
  • agent_id:
  • provider

    Provider identifier; known: 'anthropic' | 'openai' | 'glm' | 'bedrock' | 'openai-compatible' (endpoint required). Validated against the registry in src/lib/aiConfig.ts.

  • model: Model identifier, passed verbatim to the provider.
  • api_key_encrypted

    AES-256-GCM-encrypted API key (src/lib/tokenCrypto.ts encryptToken). For 'bedrock' this is a JSON-encoded {accessKeyId, secretAccessKey, region} triple, stored opaque.

  • api_key_preview: Ellipsis + last 4 chars of the raw key for masked display.
  • params

    Provider-specific knobs (maxTokens, thinking, effort, baseUrl, ...). Validated per provider by zod in src/lib/aiConfig.ts.

  • endpoint

    1373: base URL requests for this config are sent to. Null = the

    provider's default (src/lib/aiEndpoint.ts, the one suggestion list). Validated at write (validateEndpoint) and guarded at connect time.

  • api_style

    1373 D3: wire protocol for an OpenAI-compatible provider —

    'CHAT_COMPLETIONS' | 'RESPONSES'. Null = the provider's default (src/lib/aiEndpoint.ts). Refused for providers with one protocol.

  • enabled: Disabled configs are skipped by resolution (walk continues outward).
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

server_log

Log entry for the Hadron server, surfaced in hadron-portal for troubleshooting. Examples: memory sync failures, GitHub App errors, system-level events.

Properties as follows:

  • id:
  • server_id:
  • level:
  • memory_id: Set if the log relates to a specific memory.
  • message: Human-readable log message.
  • detail: Structured context (stack trace, request/response, etc.).
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

memory_log

Log entry for a specific memory, surfaced in hadron-portal for troubleshooting. Examples: sync failures, license expirations, pending edge resolution, branch conflicts.

Properties as follows:

  • id:
  • memory_id:
  • level:
  • event_type: Categorizes the log for filtering.
  • message: Human-readable log message.
  • detail: Structured context (sync diff, expired license details, etc.).
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

org_member_invitations

An invitation sent to an existing platform User to join an Organization. The role cannot be higher than that of the sender. (Contrast with UserInvitation, which is for inviting new platform users.)

Properties as follows:

  • id:
  • member_user_id: fk to OrgMember.id — the sender of the invitation.
  • recipient_user_id: fk to User.id — the recipient (an existing platform user).
  • role

    Column type is the full Role enum, but the intended grant set is ADMIN | CONTRIBUTOR | READER (you can't invite someone as OWNER — promotion happens via a separate transfer flow).

  • expires_at: When this invitation expires.
  • accepted_at: When the recipient accepted the invitation.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

user_invitations

Invitation sent out to one or more persons that do not yet have a user account. If maxActivations = 1 this invitation is single-use. If email or githubUsername is given, the new user is validated against this — which essentially locks the identity of the new person and sets maxActivations to 1.

Quota is tracked on User.maxReferrals, not on the invitation. When a new user is created from this invitation, their maxReferrals is set by the onboarding process (e.g. from the sender's remaining quota or a system default).

Race conditions: if a referral arrives at the landing page after activations exceed maxActivations, the page shows "The invitation has expired. Please contact the sender." If onboarding has started and the create-account request would push the count above the cap, the account is still created (don't block a real human on a counter).

Role bounds: userRole cannot be higher than the sender's; memberRole cannot be higher than the sender's OrgMember role in the target org.

Properties as follows:

  • id:
  • sender_user_id

    fk to User.id — the sender; NULL for system/seed invitations from Baragaun.

  • organization_id: If the new user should be added to an organization on signup.
  • slug: Random string to get a unique invite URL.
  • user_role

    Column type is the full Role enum, but the intended set is ADMIN | null (most invites grant no global role).

  • member_role

    Column type is the full Role enum, but the intended grant set is ADMIN | CONTRIBUTOR | READER.

  • new_user_id

    fk to User.id — set when the invitation is accepted and a User is created.

  • name: Recipient's name.
  • email:
  • github_username:
  • phone_number:
  • max_activations

    Maximum number of times this invitation can be accepted by a new recipient; current count is determined from UserInvitationActivation rows.

  • expires_at:
  • accepted_at

    When this invitation was accepted and the new User was created. (For multi-use invites this is set on the first acceptance.)

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

user_invitation_activations

One row per User created in response to a UserInvitation. Role bounds match UserInvitation's: userRole and memberRole cannot exceed the sender's at activation time.

Properties as follows:

  • id:
  • invitation_id: The invitation that was accepted.
  • user_id: The newly created User.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

email_verification_tokens

Temporary token for email verification during signup.

Properties as follows:

  • id:
  • email:
  • token:
  • expires_at:
  • used_at:
  • created_at:
  • client_state_hash

    505 session-fixation binding: SHA-256 of the browser nonce the portal set

    (HttpOnly cookie) when the magic link was REQUESTED. Carried into the login handoff code's clientStateHash at verify time so the browser that redeems must be the one that requested the link. NOT NULL in practice (POST /auth/email requires clientState); nullable only for forward-compat.

compiled_prompt_revisions

2046 (S9, R38): the immutable provenance of ONE compiled boot-prompt

revision, written by the compile in the same transaction as that revision. Keyed by the revision, not the node: a recompile inserts a new row and never rewrites an older one (an UPDATE is refused at the SQL layer). It records what the compile selected (the root source and every include or replacing node, each as {nodeId, revNo, hash} with its effective selection settings and its place in the expansion), never copied source text, names or titles. The live compiled-from edge is a derived index of the LATEST compile; this row, read through readCompiledRevision, is the authority for a given revision. Operational state: excluded from revisions, approval and content hashes.

Properties as follows:

  • compiled_node_id:
  • compiled_rev_no:
  • content_hash: SHA-256 hex of the compiled text this revision holds.
  • target_kind: AGENT | APP_AGENT | WORKER: the target this revision was compiled for.
  • target_agent_id:
  • target_app_id:
  • target_worker_id:
  • provenance: CompiledProvenance (src/lib/bootCompile/provenance.ts).
  • occurrence_count:
  • compiled_by:
  • created_at:

node_revisions

A versioned snapshot of a Node's content. Written every time a Node is updated, so the full history is recoverable.

Properties as follows:

  • id:
  • node_id:
  • memory_id

    Memory this snapshot's content belonged to at capture time. A node can be MOVED across memories (moveNode keeps the stable id), so gating revision history by the node's CURRENT memory alone would leak snapshots captured while the node lived in a memory the caller can't read (#602 / Codex P1). Every snapshot site stamps this; nullable only for legacy rows predating the column (backfilled to the node's current memory — the read gate treats NULL as the current memory).

  • loc:
  • name:
  • alias:
  • description:
  • abstract

    Paragraph summary at the time of the snapshot. Spec 031. Added in the US1 implementation when the live Node.abstract column landed — revision history would otherwise silently drop abstract edits.

  • abstract_origin_hash

    Revision snapshot of Node.abstractOriginHash at capture time (cor:dmo:020:03, cor:dmo:060:02). Restored verbatim by restoreNodeRevision. A restored NULL on a node with both an abstract and content means the abstract is unverified, neither stale nor fresh. A NULL on a node with no abstract or no content needs no check.

  • content:
  • tags:
  • node_type:
  • object_type: #725 — collection discriminator at capture time (parity with nodeType).
  • is_link:
  • properties:
  • data:
  • seq:
  • is_runnable:
  • role

    1201 — Node.role at capture time. In the curated subset for a specific

    reason rather than for parity: the escalation path #1202 exists for is CLEARING a governed role, and a history that cannot show the role cannot show the un-governing.

  • llm_model:
  • ai_agent:
  • authorship_kind

    1326 — pre-edit content attribution, distinct from editedBy (the actor

    taking this snapshot for the next edit). NULL on legacy snapshots.

  • authored_by_task:
  • authored_by_revision:
  • authored_by_human:
  • authored_at:
  • edited_by

    620: the User.id of the editor, when a user is known — nothing

    else goes here anymore. Historically this column was overloaded (reason ?? clientId ?? userId, so it held edit rationales, OAuth identity strings like "github:<login>", or a User id); the #620 migration moved identity strings to editedByInfo, rationales to revLabel, and backfilled from createdBy where that held a User id.

  • edited_by_info

    620: what we know about the editor when no User.id is available.

    Identity-string forms in the wild: "github:<login>" / "email:<addr>" / "user:<id>" (AuthContext.clientId) and "app:<App.id>" (App-key principals).

  • edited_by_worker_id

    1610 — the Worker / Agent behind the edit this snapshot records,

    beside editedBy (the user). Set from the snapshot editor (editorFromAuth), so the lazy reconcile, which builds its own editor, records none.

  • edited_by_agent_id:
  • rev_label

    620: user-settable label for this revision (updateNodeRevision

    mutation; REV_LABEL_MAX_LEN cap). Also captures the #88 reason arg at snapshot time — the edit rationale that previously squatted in editedBy (legacy reasons were migrated here).

  • changes

    620: which node fields the edit that took this snapshot changed

    (e.g. ["abstract","tags"]). The snapshot itself is the PRE-edit state, so changes describes the delta between this snapshot and the state that replaced it. Empty for legacy rows (NULL reads as []).

  • approved_by

    620/#1591: User who approved this revision, copied from the live

    node's approval when this revision is snapshotted (edited away) while approved. The approval of record is on Node (see Node.approvedRevNo); these columns are its history.

  • approved_by_info: #1591: the approving principal when no User.id is known.
  • approved_at: #1591: when this revision was approved.
  • approval_hash: #1591: approval hash v1 recorded when this revision was approved.
  • rev_no

    696: per-node MONOTONIC revision number (1, 2, 3, …) — the stable atom

    in the hrn:noderev:<root>:<mem>:<loc...>:<rev> URN (rendered r<N>). Minted race-safely from Node.revSeq (atomic increment) inside the same tx that inserts the snapshot. Nullable only for legacy rows predating the column (backfilled per-node by createdAt order in the migration).

  • created_by:
  • created_at:

node_content_validation_reports

1326 — append-only content-validation evidence. It names the exact Node

revision and validation-task revision observed by its producer. Reports do not edit Node, mint an authorship stamp, or fire node-written events. A late report for revision N stays historical when live content reaches N+1.

Properties as follows:

  • id:
  • node_id:
  • memory_id

    Snapshot of the holding memory, so a later cross-memory move cannot disclose this report to a reader of only the new memory.

  • node_rev_seq:
  • validation_task_id: Stable Node.id values rather than FKs: task deletion preserves history.
  • validation_task_rev_seq:
  • outcome:
  • reported_at:
  • run_id: Optional producer-run identity for idempotent insertion by #1332.

pending_setups

Temporary record holding an encrypted API key for a newly provisioned workspace, consumed during first-time setup. The raw key is the hdr_app_<…> value, shown once via /setup/info.

Properties as follows:

  • id:
  • user_id:
  • app_id: The workspace's App; ON DELETE CASCADE.
  • raw_key_encrypted: AES-256-GCM-encrypted raw API key.
  • consumed:
  • created_by:
  • created_at:

exchange_connections

A connected email mailbox (identity record). Provider state — refresh tokens, Graph subscriptions — lives in the provider capability tool (hadrontool-ms-exchange, #396); mail operations route through src/lib/emailClient.ts using toolConnectionId.

Properties as follows:

  • id:
  • organization_id:
  • user_id:
  • mailbox_email

    The mailbox/account email address; (organizationId, provider, mailboxEmail) is unique — provider-scoped so a calendar connection (provider 'google-cal') for the same Google account COEXISTS with its mail connection instead of overwriting it (PR-638 Codex P1).

  • display_name:
  • provider

    Email provider backing this connection — the emailClient dispatch key (#396: one capability tool per provider; 'ms-exchange' today).

  • tool_connection_id

    The provider tool's connection id. NULL only for legacy rows whose token hasn't been transferred yet (scripts/admin-transfer-exchange-tokens.ts).

  • refresh_token_encrypted

    LEGACY (#396): AES-256-GCM-encrypted MS Graph refresh token, kept (NULL for new rows) only as the rollback path until the one-time core→tool transfer is verified; a follow-up migration drops it.

  • sync_enabled

    Soft toggle — operator can pause sync without removing the connection.

  • sync_status:
  • last_sync_at:
  • last_error: Error message from the last failed sync.
  • webhook_subscription_id: MS Graph change-notification subscription id.
  • webhook_expires_at

    Subscription expiry — MS Graph webhooks are short-lived; the renewer cron job watches this column.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

connection_flows

2913 (cor:dmo:080:04 "Finding the connection a flow made"): where one GraphQL-started connect flow is. Created

pending by startConnection; settled once by the callback with the connection id (the existing row on a reconnect) or the done page's failure code. Readable only by userId, for one hour from startedAt judged on the database clock. connectionId is a plain id, not a relation: a flow that resolved keeps saying which connection it made.

Properties as follows:

  • id:
  • user_id:
  • organization_id:
  • provider:
  • started_at:
  • connection_id:
  • failure_code:
  • settled_at:

connection_grants

User→App scoped delegation on a user-owned connection (spec-042 Track B,

593; supersedes the deferred AgentEmailGrant). Lets a connection's OWNER

grant a specific App install scoped access (e.g. mail.read) to their mailbox/calendar. Enforced in requireEmailConnection (owner OR live grant covering the operation's scope).

  • Grantee is the App INSTALL (granteeAppId), never the Agent — one Agent in two Apps/orgs is two trust contexts (the Juno fixture).
  • Owner-only create/revoke, no org-admin bypass. Revoke is a SOFT delete; liveness lookups use findFirst + deletedAt: null (never findUnique).
  • Cross-org is intended: connection org and grantee-App org may differ; the grant row is the sole authority.
  • Multiple live grants per (connection, App) are valid — union-of-scopes — so there is deliberately no unique constraint on the pair.

Properties as follows:

  • id:
  • connection_id:
  • grantee_app_id: The App install this grant delegates to (the grantee = ctx.appId).
  • granted_by_user_id: The connection owner who created the grant (owner-only create).
  • scopes

    Operation scopes covered — subset of {mail.read, mail.send, calendar.freebusy, calendar.read}. See src/lib/emailOperationScopes.ts.

  • expires_at: Optional expiry; NULL = perpetual until revoked.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

principal_grants

An individual action grant — the ADDITIVE half of the grant model (design:grant-model; evaluated by @hadron-memory/access-control as a PrincipalGrantLike). Hands one principal extra management actions within one organization WITHOUT changing their OrgMember role: the gate's effective allow-set is union(role bundle, live grants). Multiple live grants per (principal, org) are valid = union-of-actions (no unique constraint — the ConnectionGrant precedent). Revocation is soft delete; expiry optional (NULL = perpetual). Liveness (deletedAt + expiresAt) is filtered IN the gate's query, never after it.

Properties as follows:

  • id:
  • principal_type: 'USER' (v1). Reserved for future app/agent principals.
  • principal_id: The granted user (v1: principalType='USER').
  • organization_id:
  • actions

    Allowed actions — the access-control matcher grammar: exact ('memory.clone'), prefix ('memory.'), or ''.

  • expires_at: Optional expiry; NULL = perpetual until revoked.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

slack_connections

One Slack workspace install of the Hadron Slack app (spec 043). Org-owned at WORKSPACE granularity (decision 1) — unlike the App-owned TelegramConnection design and the user-owned ExchangeConnection. defaultAppId names the Hadron App that serves /hadron commands from this workspace; per-channel App overrides are a later binding table. The tokens live ENCRYPTED IN THE TOOL (hadrontool-slack) — core stores identity only, and no token ever appears in a GraphQL field.

Properties as follows:

  • id:
  • organization_id:
  • default_app_id: The Hadron App that serves commands from this workspace.
  • provider: The slackClient dispatch key ('slack' today).
  • tool_connection_id

    The provider tool's connection id — the ops-call handle and the events-ingress resolution key.

  • team_id: Slack workspace (team) id, e.g. "T0123456789".
  • team_name:
  • bot_user_id: The bot's Slack USER id ("U…") — the sender on messages it posts.
  • bot_id

    The bot's BOT id ("B…") — what bot message EVENTS carry as bot_id. Distinct from botUserId; the bridge loop filter needs BOTH (spec 043 decision 8, PR #594 review). Don't "simplify" to one column.

  • status

    'ACTIVE' | 'ERROR' — mirrors the tool's connection-status vocabulary (there is no sync loop here, so SyncStatus does not apply).

  • last_error: Error message from the last permanent provider failure.
  • created_at:
  • created_by:
  • updated_at:
  • deleted_at:
  • deleted_by:

slack_event_receipts

Envelope-dedupe receipts for the at-least-once Slack events ingress (spec 043 decision 5): the tool's persist-before-ack inbox may deliver an event more than once (a crash between core's 2xx and the tool's row delete), so dispatch INSERTs here first and drops duplicates on conflict. connectionId is the TOOL's connection id — dedupe runs before resolution, so no FK by design.

Properties as follows:

  • id:
  • connection_id:
  • envelope_id:
  • created_at:

webfetch_poll_bindings

Core-owned routing/audit binding for a sidecar-owned webfetch poll job. Poll state, scheduling, snapshots, and credentials remain in the sidecar; this immutable snapshot answers which already-authorized run principal an at-least-once event may wake.

Properties as follows:

  • job_id:
  • source_run_id:
  • organization_id:
  • app_id:
  • agent_id:
  • user_id:
  • entry_node_urn:
  • policy:
  • credential_secret_id

    The resolved Secret row a credentialed poll used (#677 — audit provenance; supersedes the #628 credentials_node_urn node scheme).

  • url: Query- and fragment-free URL for audit/event-origin validation.
  • cancelled_at:
  • created_at:

webfetch_event_receipts

Durable completed-dispatch receipt for the at-least-once webfetch event ingress. An absent snapshot hash is represented by the empty string so the compound unique key remains effective under Postgres NULL semantics.

Properties as follows:

  • id:
  • job_id:
  • snapshot_hash:
  • kind:
  • routed_run_id:
  • created_at:

mcp_servers

Registered EXTERNAL MCP server — the org-scoped registry behind the hadrontool-mcp conduit (headless runs calling third-party MCP tools). The conduit tool is stateless and Hadron-blind (cor:int:030:01); core owns identity, governance, and the encrypted static headers. A run reaches a server's tool via the run-tool name mcp__<slug>__<tool>, and every call is gated by the policy chain as tool.mcp__<slug>__<tool> plus the run's action budget — this row grants nothing by itself.

Properties as follows:

  • id:
  • organization_id:
  • slug

    Run-tool name segment (mcp__<slug>__<tool>); lowercase [a-z0-9-], unique per org. Keep it short — provider tool-name caps are ~64 chars.

  • name:
  • url

    Streamable-HTTP MCP endpoint URL. The conduit refuses private-network hosts unless explicitly allowed (SSRF guard, dev only).

  • headers_encrypted

    AES-256-GCM-encrypted JSON object of static request headers (src/lib/tokenCrypto.ts), e.g. {"Authorization":"Bearer ..."} — v1 auth posture (no OAuth). WRITE-ONLY on the API surface: resolvers expose only a hasHeaders boolean, never the value.

  • tool_allowlist: Exposed-tool allowlist; empty = every tool the server advertises.
  • enabled

    Disabled servers fail run-tool resolution loud (unknown tool), same posture as an unregistered slug.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

secrets

One named, owner-scoped secret — the general secret store (#677). Polymorphic owner (user | org | app | memory) — deliberately no FK: entitlement is checked at resolution time under the caller/run principal, and a dangling owner simply never resolves. A bare name resolves via the CSS cascade, most-specific-first: memory → app → user → org. kind is extensible (generic opaque; webfetch-auth typed: metadata { type, urlPrefix }, origin-bound at use).

Properties as follows:

  • id:
  • owner_type:
  • owner_id:
  • name: Cascade-resolution key; unique per owner; lowercase [a-z0-9-], max 64.
  • kind:
  • metadata

    The NON-secret, inspectable half — safe on every read surface. A reader can see THAT a secret exists and (webfetch-auth) WHERE it applies without decrypting.

  • value_encrypted

    encryptToken(JSON.stringify(payload)) — AES-256-GCM under the platform key (src/lib/tokenCrypto.ts). NEVER selected into a read surface: redaction by construction, same as the aiConfig / HA / Resend / MCP registries. Rotation is overwrite (updateSecret), no versioning (v1).

  • key_id

    Key-rotation lineage headroom; unused (null) while HADRON_ENCRYPTION_KEY is the only key.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

home_assistant_instances

One registered Home Assistant instance — the org-scoped registry behind the hadrontool-home-assistant capability tool (hadron-server#640). Same posture as McpServer: the row grants nothing by itself (every run-time call walks the policy chain as tool.ha__<slug>__<op> + action budget), hard delete by design, slug immutable because flow nodes reference it inside data.tools names.

Properties as follows:

  • id:
  • organization_id:
  • slug

    Run-tool name segment (ha__<slug>__<op>); lowercase [a-z0-9-], unique per org. Keep it short — provider tool-name caps are ~64 chars.

  • name:
  • url

    Home Assistant base URL (e.g. https://ha.example.com or a Nabu Casa remote URL). The tool refuses private-network hosts unless its HA_TOOL_ALLOW_PRIVATE_NETWORKS flag is set (self-hosted posture).

  • token_encrypted

    AES-256-GCM-encrypted long-lived access token (src/lib/tokenCrypto.ts). WRITE-ONLY on the API surface: resolvers never return it; update replaces it.

  • op_allowlist

    Exposed-op allowlist over the closed HA_OPS catalog; empty = every op. Lets an admin register a READ-ONLY instance (no call_service).

  • enabled

    Disabled instances fail run-tool resolution loud (unknown tool), same posture as an unregistered slug.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

resend_senders

One BYO Resend sender for an organization. Core owns and encrypts the API key; the stateless hadrontool-resend sidecar receives it only for an already-authorized send. One sender per org keeps credential selection deterministic and outside model control.

Properties as follows:

  • id:
  • organization_id:
  • from_address

    Fixed sender identity accepted by Resend, e.g. Hadron Agent <agent@example.com>. Not secret.

  • api_key_encrypted

    AES-256-GCM-encrypted Resend sending-access API key (src/lib/tokenCrypto.ts). WRITE-ONLY on the API surface.

  • enabled:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

waiting_list

Pre-launch waitlist signup capture from the marketing site. Holds an email plus an optional free-form "what features would you most want?" answer. Not connected to User (signups happen before the user has an account).

Properties as follows:

  • id:
  • email:
  • requested_features:
  • created_at:

apps

The runtime deployment of an Agent in some Organization — what someone installs when they pick an Agent off the marketplace (or install one from their own org). Holds credentials, surfaces, optional AI override, members, and per-deployment memory pivots. Per Constitution Technology Invariant #6, this is also the unified caller-identity entity that authenticates against the Hadron platform.

Per (org, Agent) install: typically one App per pair. Multi-install of the same Agent across orgs is supported and explicitly isolates app- and personal-class memory at (app_id, …) keys.

Auth credentials live on AppKey rows (one or many per App, independently revocable). The wire-token prefix hdr_app_ and the appKey developer-facing identifier are deliberately preserved by 008 — there is no rename.

008-agent-installation drops the AppAgent join: an App now references its Agent directly via agentId. The legacy OPERATE/DEVELOP role distinction is removed (system memory is universally read-only from any App context — DEVELOP-from-App is gone per R-10).

Cascade behavior: hard App deletion cascades to AppKey, AppLogEntry, AppMember, and the App's app/personal-class Memory rows. The orphan-retention behavior in 008 FR-015 (personal memory survives an AppMember removal) is independent — it's a row delete in app_members, not in apps.

Properties as follows:

  • id:
  • name: Display name.
  • policy

    App-layer action-policy link (cor:acl:040:02) — same allow-list shape as Organization.policy; NULL = no restriction. Org-admin-authored (updateApp). Snapshotted into AppRun.policy at mint.

  • urn

    Globally unique identifier; derived from org.urn + ":" + slug.

    Spec 021 (FR-027) — uniqueness is now PARTIAL. The DB-level constraint is apps_urn_active_uniq WHERE uninstalled_at IS NULL (declared in the 021 migration). The same URN can legitimately appear on multiple rows: one active (uninstalledAt IS NULL) plus N uninstalled history rows. Prisma's field-level @unique declaration was REMOVED because it would generate a non-partial global unique index that fights with the migration.

    Callers MUST use findFirst({ where: { urn, uninstalledAt: null } }) for active-row resolution per FR-028 resolution precedence; the findUnique callers in resolvers.ts were migrated to this pattern in PR #124.

  • organization_id:
  • owner_user_id

    User owner of a user-owned App (rooted on the bare <handle> — #697 v2, no @ sigil). The org/owner XOR is ENFORCED — chk_app_owner_xor in post-push.sql: (organization_id IS NULL) <> (owner_user_id IS NULL) — so exactly one of organizationId/ownerUserId is non-null.

  • create_user_permission:
  • identify_user_method:
  • session_timeout_seconds:
  • session_dormancy_days

    Ruling DY-5: days of no activity after which a lapsed worker session of this App is DORMANT. No agent act resumes a dormant session (DA/DY-1); only an explicit rebind by its human holder brings the worker back. The security half of Holger's session-lifetime principle: a long-forgotten session must not start acting again on its own.

  • agent_sessions_expire

    Ruling DY-3: whether startAgentSession stamps a hard expiresAt by default. False = this App's agent sessions have NO hard expiry unless the call asks for one (a caller-supplied sessionTimeoutSeconds, still capped by the App ceiling). A forgotten one is still bounded: past the App's sessionDormancyDays it no longer binds (bindSession, DY-5).

  • anonymous_ttl_days:
  • ticker_min_cadence_seconds

    cor:agt:080:05 — the App's ticker settings (one set per App), changed only by whoever manages the App. Bounds are enforced in the write (TICKER_SETTINGS_OUT_OF_RANGE) and pinned by CHECK chk_apps_ticker_settings (prisma/ticker-invariants.sql). The cadence floor, also the wake-rate ceiling: >= 60.

  • delivery_busy_delay_seconds: #2025 / cor:agt:080:05 — Proposed bounds: 1..86400 whole seconds.
  • delivery_stuck_window_seconds: Proposed bounds: 1..604800; strictly greater than busy delay + cadence floor.
  • delivery_standby_enabled: Stored OFF; enabling is refused until #2023 supplies standby behavior.
  • delivery_check_period_seconds

    2138 §3.2 — a worker with a task is expected to check its team channel every period (seconds);

    the team ticker's cadence is set together with it.

  • delivery_failed_checks_to_overdue: #2138 §3.2 — OVERDUE after this many missed periods (+5 min slack, hard-coded); at least 1.
  • delivery_dark_alarm_window_seconds

    2755 — a worker's unacknowledged due wake raises the dark-worker alarm after this many seconds (300..86400;

    default 1800). Not deliveryStuckWindowSeconds (deprecated, cor:agt:050:26's window).

  • team_paused_at

    2138 §3.6 — a TEAM pause, separate from every worker's own pausedUntil: a worker cannot lift

    it, and ending it never clears a self-pause. NULL = not paused.

  • team_resumed_at: #2138 §3.6 — when the last team pause ENDED; restarts every worker's check clock (the status is not OVERDUE the moment a pause lifts). NULL = never paused.
  • ticker_self_subscribe_cadence_seconds: The fastest ticker a worker may subscribe ITSELF to: [floor, 86400].
  • ticker_live_cap: How many live tickers the App may have: [1, 100].
  • wake_daily_budget: Null = derived (subscribed workers x (86400 / self-subscribe cadence) x 2).
  • properties

    3125 S1 (cor:dmo:050:02, cor:dmo:050:20): the App's own JSON object, the App equivalent of Node.properties.

    Written whole by whoever manages the App (setAppProperties); never a credential. The platform reads only the reserved taskIntegrations key (cor:agt:120:01). NULL = no properties. CHECK: an object when set.

  • properties_revision

    3125 S1 (V34): moved by every changing setAppProperties write, the optional expected-revision check's counter.

    Its own column, not updatedAt, which every other App write moves.

  • run_team_snapshot_enabled: Ruling0112: only a managing person may opt this App’s runs into read-only roster/task access.
  • app_type

    Deprecated — superseded by surfaces. Scheduled for removal in a follow-up cleanup spec (per 008 R-4); kept in place to avoid spurious portal churn.

  • role

    Default member role applied when the Agent's installation_policy.memberRoles doesn't apply.

  • description:
  • agent_tools: Tools this App's agent can access; default [].
  • expires_at:
  • training_mode

    Migrated from the dropped app_agents.training_mode. Sessions through this App are flagged as training data for the Agent's owner to review. 008-agent-installation FR-022.

  • surfaces

    Free-form per 008 R-9; v1 known values: 'chat', 'slack', 'mcp', 'web'. Surface enforcement (which features are gated on which surfaces) is handled by the portal/app code; chat-tab gating in hadron-portal#187 reads surfaces.includes('chat'). 008-agent-installation FR-014.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • uninstalled_at

    Soft-uninstall timestamp per spec 021 FR-025. Null = active install; set = uninstalled (read-only, write-rejected with "app uninstalled" error including cascade to child agents/memories/nodes per FR-026). Reinstall after soft-uninstall is allowed via the partial unique index apps_urn_active_uniq WHERE uninstalled_at IS NULL (declared in the 021 migration; supersedes Prisma's @unique on urn at the DB level).

  • urn_normalized_at

    Online URN-shape migration gate (spec 021 FR-032, repurposed for the #697 v1→v2 emission flip; transient). Null = pre-normalization row (read through the legacy parser); set = row normalized onto the flat v2 form (<root>:<slug>, single colon). Dropped once 100% of rows are migrated. TODO(spec-021-cleanup): drop this column once the FR-032 migration completes — tracked under the spec-021 cleanup follow-up. The apps_urn_migration_pending_idx partial index goes with it.

  • urn_migration_failed_reason

    Spec 021 sentinel for data-defect rows during the FR-032 migration. Non-null = the row's urn failed normalization; the migration job skips it on subsequent passes (avoids infinite retry). Transient; dropped with urnNormalizedAt. TODO(spec-021-cleanup): drop alongside urnNormalizedAt.

  • legacy_urn

    697 stored alias map: the pre-v2 (v1) URN this row was migrated FROM

    (see Memory.legacyUrn). Null until the online migration flips urn to v2.

  • default_channel_id

    Spec 049 Phase 4 (D-2026-09-13-007 D2): the App's DEFAULT Channel — the row the team chat became, what teamChatMessages(appRef) addresses and what an installed Agent's default register row points at. Set at App creation (ensureDefaultChannel) and by the Phase 4 backfill (the OLDEST live chats:team root, the resolver's own ordering). A nullable FK rather than a flag on the Channel: two defaults per App would be a state no CHECK refuses.

app_keys

An API key for an App, independently revocable; multiple keys per App. The raw key carries the canonical hdr_app_ prefix and is shown once at creation; only the SHA-256 hash is stored. (SHA-256, not bcrypt — bcrypt's per-hash salt would prevent the constant-time keyHash lookup the auth resolver does. The raw key is a 256-bit random value, so dictionary attacks against the hash are not a concern.)

Auth path: the resolver at src/middleware/auth.ts accepts hdr_app_-prefixed bearer tokens, looks up the AppKey by SHA-256 hash, and resolves the principal to the parent App. Memory access is then gated by src/mcp/access-control.ts, which reads App.agentId directly (the legacy AppAgent join was dropped in 008-agent-installation) and folds the Agent's systemMemoryId + memoryItems into the access map.

Client config field: hadron-client reads the AppKey value from the appKey field of .hadron/config.json. The env var name HADRON_CLIENT_KEY describes location (the client process), not the entity.

Properties as follows:

  • id:
  • app_id:
  • key_hash: SHA-256 hash of the raw hdr_app_<…> key.
  • key_preview: Last 4 characters of the raw key for masked display.
  • label: Human-friendly name for this key.
  • created_at:
  • created_by:
  • last_used_at:
  • revoked_at:

app_members

The User↔App membership join with a per-member role. Spec: 008-agent-installation FR-004.

Per-User lifecycle is reserved for a future spec — there is no revokedAt / expiresAt column. Removing a member is a row delete; the user's personal-class Memory at (app_id, user.id) is retained by default as an orphan (FR-015) and re-attaches automatically if the user later rejoins the same App.

No deletedAt — soft-delete is meaningless for a pure join.

Properties as follows:

  • app_id:
  • user_id:
  • role

    Free-form string validated at write-time against the parent Agent's installation_policy.memberRoles (per 008 R-7). Examples: 'owner', 'guide', 'cook'. installation_policy.maxMembers is enforced at invite-acceptance time (per FR-016).

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

agent_org_grants

The Org↔Agent license — authorizes an Org to (a) create Apps that deploy this Agent, and (b) bundle this Agent in AgentImport edges of Agents the Org owns. Spec: 008-agent-installation FR-006 / R-2.

Sibling to AgentSubscription (User↔Agent, from 005). Both share the lifecycle field shape (activatedAt, expiresAt, revokedAt, revokedBy) and the same active-status predicate. The two-table split (rather than a polymorphic subjectType + subjectId) preserves typed FK integrity and per-table indexing clarity.

For same-org installs (an Org deploying its own Agent), the grant is auto-provisioned by ensureAgentOrgGrant on first contact. Cross-org installs require an existing active grant; PUBLIC Agents can be subscribed to through createAgentOrgGrant.

No deletedAt — soft-delete is redundant with the revokedAt lifecycle.

Active-status predicate (shared with AgentSubscription via the isLifecycleActive helper):

activatedAt IS NOT NULL AND revokedAt IS NULL AND (expiresAt IS NULL OR expiresAt > now())

Properties as follows:

  • org_id:
  • agent_id:
  • activated_at: v1 default: now() on creation since billing is out of scope.
  • expires_at:
  • revoked_at

    Set by an ADMIN/OWNER of the Agent's owning org via revokeAgentOrgGrant.

  • revoked_by: fk to User.id — audit trail for who revoked.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

agent_imports

A directed dependency edge between two Agents — "Agent A imports Agent B as a dep." Spec: 008-agent-installation FR-005 / User Story 3.

Installing the parent (a row in apps with agentId = parent) cascade-installs required deps (creates additional Apps in the same org, one per dep). Optional deps install only if the caller passes installOptional.

v1 enforces 1-level imports only — the dep itself must NOT be a parent of any AgentImport. Cycles are trivially blocked at write time (parentAgentId != importedAgentId).

Properties as follows:

  • parent_agent_id

    The Agent that does the importing (the "Suite"). ON DELETE CASCADE.

  • imported_agent_id

    The dep Agent. ON DELETE RESTRICT — deleting it would invalidate every Suite that depends on it; operators must remove the import edge first.

  • position

    Sparse-int ordering (per 008 R-8). Builders set values like 100, 200, 300 to allow easy reordering without renumbering.

  • required: Hard dep vs optional. Default true.
  • agent_org_grant_org_id

    Composite fk to AgentOrgGrant(orgId, agentId) (ON DELETE RESTRICT) — the Builder grant authorizing this import. Spec FR-005 named this column agent_subscription_id; renamed per 008 R-2 since the universal-grant role for org-level grants lives on the new AgentOrgGrant sibling, not AgentSubscription.

  • agent_org_grant_agent_id:
  • created_at:
  • created_by:

agent_subscriptions

The User-side license: "this user is authorized to use this agent." Auto-provisioned on first user-attributed contact (per controller/operations/ensureAgentSubscription.ts); revocable by an ADMIN/OWNER of the Agent's owning org. Authorizes the cross-org write from the Agent into the user's personal-class Memory.

Sibling to AgentOrgGrant (Org↔Agent, added in 008-agent-installation). Both share the lifecycle field shape and the same isLifecycleActive predicate; AgentSubscription continues to express User↔Agent grants while AgentOrgGrant covers Org↔Agent (App-creation + import-bundling) grants.

Spec: 005-agent-subscription (2026-04-30). Composite primary key on (userId, agentId).

No deletedAt — soft-delete is redundant with revokedAt.

Active-status predicate (used by the access-resolver):

activatedAt IS NOT NULL AND revokedAt IS NULL AND (expiresAt IS NULL OR expiresAt > now())

Revocation behavior (per FR-028 / FR-029): when revoked, the user's personal Memory of the Agent is retained by default — the user owns it, may want to keep their notes after a class ends. The Agent loses write access (per FR-019); the user retains read access via direct authenticated queries. The Memory.userMemoryOfAgentId pivot is preserved so the memory remains identifiable as "originally from Agent X." Single exception: if the personal Memory has zero nodes at revocation time, the platform may hard-delete it alongside the AgentSubscription (avoids orphan accumulation).

Properties as follows:

  • user_id:
  • agent_id:
  • activated_at

    v1 default: now() on creation since billing is out of scope; future billing introduces a deferred-activation path (activatedAt = null until payment confirms).

  • expires_at: Time-bounded subscriptions; NULL for non-expiring.
  • revoked_at

    Set by an ADMIN/OWNER of the Agent's owning org via revokeAgentSubscription.

  • revoked_by: fk to User.id — audit trail.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

app_log

Log entry for a specific App, surfaced in hadron-portal for troubleshooting.

Properties as follows:

  • id:
  • app_id:
  • level:
  • memory_id:
  • session_id:
  • message: Human-readable log message.
  • detail: Structured context.
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

app_agents

N:M join between App and Agent, reintroduced by spec 023.

No role column — system memory is read-only to every App regardless (the pre-008 OPERATE/DEVELOP distinction stays deleted per spec 023 FR-003). No trainingMode column — training mode is a per-App setting and lives on App.trainingMode (spec 023 FR-001; deviates from the 2026-05-12-user-installing-app summary §3 to avoid per-Agent conflicts on an App-wide setting).

Transition note: App.agentId was dropped and consumers retrofitted in Phase 2b (hadron-server#129, 2026-05-17). Install flows go through the installAgentIntoApp mutation (spec 023 US1, hadron-server#130) which writes an AppAgent row.

Cascade behavior: hard App or Agent deletion cascades to the AppAgent row. Uninstalling an Agent from an App (deleting the row) does NOT cascade-delete the (app_id, agent_id, *) memories (FR-005; orphan retention preserved). Duplicate inserts for the same (app_id, agent_id) are rejected by the composite PK.

Properties as follows:

  • app_id:
  • agent_id:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • boot_prompt_node_id

    2045 (S8, cor:agt:040:07) — the install's boot-prompt POINTER: the id of a

    compiled boot-prompt node (nodeType = 'compiled-boot-prompt'), never its source. NO foreign key: nodes are hard-deleted on some paths (deleteNode hard/subtree, memory merge, git-sync cleanup), and SET NULL would turn a deleted target (R27) into "no pointer" (R26) while RESTRICT would block those deletes. bootPromptUrn is the target's canonical URN at write time, read only when the row is gone; both are set or both NULL (chk_*_boot_prompt_pointer_pair, prisma/boot-prompt-pointer-invariants.sql). Written only through setBootPromptPointer (src/lib/bootPromptPointer.ts). The row is hard-deleted on uninstall, so a reinstall starts empty until the App's manager next compiles (cor:agt:040:06, cor:dmo:050:03).

  • boot_prompt_urn:

workers

974 — a Worker: the named casting of an installed Agent into an App

(cor:dmo:050:11, cor:agt:020:01). The Agent carries the reusable persona dressing (personaRole and its compiled boot prompt); the Worker is the local named identity ("Iris") that does attributable work. Casting is opt-in (an installed agent with no Worker row is just an agent) and requires the agent installed in the App at cast time; multiple Workers may cast the SAME agent in one App (Iris and Henry, both backend-engineer).

Name uniqueness: unique per App, case-insensitively — the functional unique workers_app_name_uniq on (app_id, lower(name)) in post-push.sql (Prisma cannot express functional uniques). Deliberately NOT filtered on retirement: a name binds to one casting forever (cor:agt:020:02 — PR trailers and chat archives reference it, and a recycled name would silently re-attribute old work).

Lifecycle: workers RETIRE (retiredAt), never soft-delete — the row must survive the agent's uninstall and keep resolving for history. There is no deletedAt; the only removal escape is the hard delete of a never-used miscast (no sessions ever bound, empty working memory). agentId is Restrict so a referenced casting can never lose its agent silently (agent deletion is soft everywhere; the hard-delete compensation paths only ever remove agents without castings).

Properties as follows:

  • id:
  • app_id:
  • agent_id:
  • name: The worker's name ("Iris") — the identity every surface renders.
  • slug

    991 — the URN atom: hrn:worker:<root>:<app-slug>:<slug>. DERIVED from

    name at cast time (deriveSlugFromName, then -2/-3… until free in the App) and permanent thereafter — there is no rename mutation, and the name it was derived from is itself permanent (cor:agt:020:02).

    This is a SECOND stored uniqueness (workers_app_slug_uniq), which cor:agt:020:02 otherwise forbids — the distinction that makes it legal is that it NEVER REFUSES: the mint iterates instead of erroring, so the name collision stays the single allocation primitive a caller can observe. That is exactly what the reverted mention-token unique (PR #979) did not do. The index exists so a race between two casts deriving one base slug cannot produce two workers sharing a URN.

  • role

    The cast-list role this filling answers ("backend-engineer"). Free string with conventions; defaults to the agent's personaRole at cast time when the caller names none.

  • signature: Per-worker signature template, delivered through S4 (cor:agt:040:04).
  • trailer: Per-worker commit trailer template, delivered through S4 (cor:agt:040:04).
  • boot_prompt_node_id

    2045 (S8, cor:agt:040:07) — this worker's boot-prompt POINTER: the id of a

    compiled boot-prompt node (nodeType = 'compiled-boot-prompt'), never its source. NO foreign key: nodes are hard-deleted on some paths (deleteNode hard/subtree, memory merge, git-sync cleanup), and SET NULL would turn a deleted target (R27) into "no pointer" (R26) while RESTRICT would block those deletes. bootPromptUrn is the target's canonical URN at write time, read only when the row is gone; both are set or both NULL (chk_*_boot_prompt_pointer_pair, prisma/boot-prompt-pointer-invariants.sql). Written only through setBootPromptPointer (src/lib/bootPromptPointer.ts). Set for customised workers only, empty otherwise (cor:dmo:050:11).

  • boot_prompt_urn:
  • memory_id

    974 — the worker-scoped working memory in the App's container

    (hrn:mem:<owner>:<app-slug>:<worker-slug>), provisioned at cast. Identity is THIS column, never the memory's URN (the #723 rule).

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • held_by_user_id

    1050 — the HUMAN holding this name. A name is held by a person, not by a

    live session: expiry, a reap, or a closed chat session never free it, and only an explicit release does.

    This is what separates the two meanings of "taken" that used to share one word (hadron-cli#487). HELD = the name belongs to someone; the answer to a second person wanting it is to cast their own, never to adjudicate whether the first is "really gone". TAKEN = a live session exists, which is only ever a question about your OWN worker. Deriving availability from session liveness is what let an agent end a mid-PR driver's session and bind as them, every step following the documented procedure (hadron-cli#492).

    Nullable because a released worker is genuinely unheld — and because a worker cast before this column existed has a holder only by backfill from createdBy. The next bind of an unheld worker holds it.

  • held_at

    When the current hold was taken — provenance for a release decision, and what an admin force-release reports.

    Both platform write paths (releaseWorker, deleteUserAccount) clear this together with heldByUserId, but the FK's ON DELETE SET NULL clears only the id, so a RAW hard delete of a user can leave a vestigial timestamp here. Worker.heldAt therefore masks it to null whenever there is no holder, so the API invariant — heldAt is set exactly when heldByUserId is — holds because it is enforced rather than remembered. A CHECK cannot do that job: it would make the FK's own SET NULL violate it.

  • retired_at

    Retirement instant — the name stays reserved forever (cor:agt:020:02). A retired worker stops authoring (team chat's worker-App pin checks retirement at post time) and refuses new session bindings.

  • retired_by:
  • reports_to_worker_id

    1726 — the one Worker this worker reports to (Holger, 2026-10-09): a

    non-retired Worker of the same App, never itself, and never a cycle. Null reports to nobody (the top of a team, or an unclaimed worker). A property of the casting, not of a session: binding, rotating or ending a session leaves it alone. Written only by src/lib/workers/reportsTo.ts, which also appends the worker.reports-to event that keeps its history.

  • explicit_no_team: S12: explicit human choice; false + null reportsTo is UNSET, never inferred NO_TEAM.
  • terminal

    2771 (proposed cor:agt:070:09) — the latest terminal report a HOST made for this worker, built by the server

    (src/lib/workerTerminal.ts): host {id,label}, status, prompt, reason (a closed code), lastTurnAt, checkedAt, reportedAt. Null until a host first reports. A stored report that DECIDES NOTHING: it feeds no checkStatus, availability, matcher, stall rule or alarm. No screen text is ever stored; chk_workers_terminal_shape (in prisma/host-operation-invariants.sql) allows exactly the keys above, so a write that bypasses the resolver still cannot store more. Read behind maySeeWorkerInternals (cor:dmo:050:11).

memory_shares

Asymmetric cross-user grant for personal-class memory (spec 023 US3 / FR-017–FR-022). Composite PK (memoryId, granteeId) — one row per (Memory, grantee).

Scope: applies ONLY to personal-class Memories (FR-018). Application-layer guard in createMemoryShare.ts enforces this.

Grantor semantics (FR-019): grantorId is the principal (Memory.userId), recorded explicitly so the row is self-describing without a JOIN to memories at read time. The API actor (which may be an App backend acting on the principal's behalf) is recorded in createdBy.

No time-window (FR-021): isolation between grantees over time is modeled by creating a new personal Memory per pairing — not by time-slicing one Memory.

Properties as follows:

  • memory_id:
  • grantee_id:
  • grantor_id:
  • role:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

memory_members

Symmetric team membership for group-class memory (spec 023 US4 / FR-026–FR-031). Composite PK (memoryId, userId) — one row per (Memory, member).

Scope: applies ONLY to group-class Memories (FR-027). Application-layer guard in addMemoryMember.ts enforces this.

Role capabilities: reader — read. writer — read + write nodes within the Memory. owner — read + write + manage member list, delete/rename the Memory, change Memory configuration (FR-036).

Last-owner protection (FR-038): the platform rejects removal or demotion of the sole remaining owner. The MemoryMember row can still be deleted; the operation-layer guard enforces the invariant (removeMemoryMember.ts, updateMemoryMemberRole.ts). FR-031: removing the last non-owner does NOT delete the Memory.

Properties as follows:

  • memory_id:
  • user_id:
  • role:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

user_api_keys

User-owned API key — the credential primitive for user-scoped MCP access (spec 025-oauth-for-mcp; D-2026-05-13-001, D-2026-05-17-001). Mirrors AppKey but resolves to a User instead of an App. The raw key is hdr_user_<…>; we store SHA-256 (not bcrypt) for the same reason AppKey does — direct hash lookup needs a deterministic hash, and the 256-bit raw key (32 bytes / 64 hex chars) already makes dictionary attacks irrelevant.

Tokens issued by the OAuth /token endpoint share this shape and storage path so a single resolveUserApiKey middleware validates both portal-minted and OAuth-issued tokens (FR-015). The path the key arrived through is recorded in issuedVia (not createdBy); see the column docstrings.

Audit fields omitted (matches AppKey precedent): no updatedAt / updatedBy / deletedAt / deletedBy. UserApiKey rows are append-once with a single terminal state transition (revoked); revokedAt carries the lifecycle info, and there is no edit operation. Soft-delete is meaningless for a revocable credential.

2659 (cor:dmo:070:03): its user may HARD-delete a key

(deleteUserApiKey); the trace is a separate UserApiKeyDeletion row.

Properties as follows:

  • id:
  • user_id:
  • key_hash: SHA-256 hash of the raw hdr_user_<…> key.
  • key_preview: Last 4 characters of the raw key for masked display.
  • label: Human-friendly name for this key.
  • created_at:
  • created_by

    Actor that minted this key. Schema-wide convention: User.id of the actor. For self-service v1 this equals userId; the column exists for future admin-issued paths (where actor != owner).

  • issued_via

    Issuance identity: portal for direct sign-in, oauth:<client_id> for OAuth issuance, inherited from an authenticated minting key. Nullable historical provenance remains unknown. Distinct from the User actor.

  • oauth_scopes

    Immutable OAuth scopes copied from the authorization code at token redemption. Empty means an unrestricted portal/legacy user key. There is deliberately no DB default: every issuance path writes the exact grant.

  • last_used_at:
  • revoked_at:
  • hidden_at

    2298: the owner hid this REVOKED key from their default list. Display

    state only: never read by authentication, revocation or lineage.

  • minted_by_key_id

    Authenticated credential that minted this key (#1253). Null means direct issuance, unknown legacy ancestry, or (#2659) a minting key its user has since deleted, the break recorded once in that key's UserApiKeyDeletion row; never inferred/backfilled.

  • origin_sign_in_id

    1897 / R66: the factor-protected sign-in this key descends from, directly

    or through minting keys. Immutable, server-derived, never inferred from email/time/issuedVia; null = direct issuance or legacy (S6), never backfilled.

impersonation_sessions

Admin-impersonation audit record AND revocation source of truth. One row per impersonation session: an org ADMIN/OWNER (or platform admin) viewing the platform read-only as the target user, scoped to the single organization shared by admin and target. The target's other organizations and all personal-class resources (personal/private memories, chats, mailbox, assets, personal credentials) stay invisible.

A session is LIVE iff endedAt IS NULL AND expiresAt > now(). Expiry is derived from expiresAt at read time and never written back.

endedAt and endedBy together distinguish how a session finished: - endedAt set, endedBy set — a person explicitly stopped it. - endedAt set, endedBy NULL — the system REVOKED it (#878). Every request re-derives both parties' current org roles, so losing the admin role, a promotion that breaches peer-or-below, the target leaving the org, or the admin's account being deleted ends it at once. - endedAt NULL, past expiresAt — it simply lapsed.

Rows are never deleted by the stop path — the table is the durable audit trail (who impersonated whom, where, when).

Properties as follows:

  • id:
  • admin_user_id: Actor (the admin). Schema-wide audit-actor convention: User.id.
  • target_user_id: The member being impersonated.
  • organization_id: The shared org that scopes the impersonated session's reads.
  • reason

    Optional support/diagnostic reason supplied at start. Capped at the resolver (USER_API_KEY_LABEL_MAX_LEN precedent).

  • created_at:
  • expires_at:
  • ended_at

    Explicit-stop timestamp. NULL while live or when the session merely lapsed by TTL.

  • ended_by

    User.id of whoever stopped it early (the admin in v1 — never the target: the impersonated context's self-stop records the actor).

oauth_clients

OAuth 2.1 client registry (spec 025-oauth-for-mcp; D-2026-05-17-002). Rows are populated by POST /oauth/register (RFC 7591 DCR) or seeded explicitly. Public clients only (no clientSecret); PKCE S256 is the auth proof. Per Q-025-001, only the 'test' row will be seeded by prisma/seed.ts (spec 025 task T009 — not yet in this PR); 'claude-desktop' and other real clients self-register via DCR.

PK note: clientId is the PK (no separate cuid id) because clientId is the natural key — it's the public, immutable identifier the client sends on every /authorize / /token request and is referenced by AuthCode.clientId as the FK target. Precedent for a non-cuid PK: Session.id is caller-generated. Diverges from PR 137's reference (which carried a separate cuid id) — see spec-kits/specs/025-oauth-for-mcp/data-model.md §OAuthClient.

Carries the full standard audit-field set per the schema-top convention because edit / delete affordances are anticipated (admin "rename a client", "rotate redirect URIs", etc.); v1 has no such surface, but the columns are cheap to add now and would otherwise need a backfill later.

Properties as follows:

  • client_id

    The public client identifier. DCR-registered: dcr_<32 hex> (16 bytes / 128 bits). Seeded fixtures use stable identifiers like 'test'. Primary key.

  • client_name:
  • redirect_uris

    Allowed redirect URIs. /authorize must reject any redirect_uri not present here (OAuth 2.1 §3.1.2).

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:
  • expires_at

    155: when an unused DCR client becomes collectable. Set to now + 30

    days at registration and pushed forward by each token redemption; the GC job (src/jobs/gcOauthClients.ts) soft-deletes a client 7 days past it. NULL never expires (seeded and hand-made clients).

auth_codes

Short-lived OAuth authorization code (spec 025-oauth-for-mcp; RFC 6749 §4.1). Issued by POST /oauth/authorize on decision=approve, redeemed once at POST /oauth/token. Stores PKCE S256 challenge + RFC 8707 resource indicators for verification at redemption. Single-use via race-safe updateMany-with-conditional redeemedAt: null pattern (FR-013). PKCE / resource mismatch at /token also marks redeemedAt to prevent probing.

Code storage: the raw code value is hashed (SHA-256) before storage, matching AppKey.keyHash and UserApiKey.keyHash — auth codes are credentials in their 10-minute redemption window and should not be plaintext in the DB. /oauth/authorize returns the raw code to the client; /oauth/token hashes the supplied code and looks up by hash. Diverges from PR 137's reference (which stored plaintext) — see spec-kits/specs/025-oauth-for-mcp/contracts/oauth-endpoints.md §POST /oauth/token.

Audit fields omitted (matches AppKey precedent): no updatedAt / updatedBy / deletedAt / deletedBy. AuthCode rows are append-once with two terminal state transitions (redeemed / expired); redeemedAt and expiresAt carry the lifecycle info. Soft-delete is meaningless for a single-use, expiring credential.

Properties as follows:

  • id:
  • code_hash

    SHA-256 hash of the raw code value handed to the client. Looked up by hash at /token to avoid plaintext credentials in the DB.

  • client_id:
  • user_id:
  • redirect_uri:
  • code_challenge: PKCE S256 challenge value (base64url, no padding).
  • resource

    RFC 8707 resource indicator(s) captured at /authorize. Multi-valued per RFC 8707 §2; v1 MCP usage populates a single element (the MCP endpoint URL). Application enforces ≥1 element.

  • oauth_scopes

    Immutable OAuth scopes approved by the user. Copied exactly to the UserApiKey minted when this code is redeemed. No DB default: the authorize path must always write the approved grant.

  • expires_at:
  • redeemed_at:
  • created_at:
  • created_by

    Actor that initiated the /authorize request that minted this code. Resolves to the signed-in User; equals userId in self-service v1.

  • sign_in_id

    1897: the sign-in this code descends from (null = not factor-protected;

    never inferred). Immutable, same owner as userId.

passkey_ceremonies

1631 S2a: one browser-bound, purpose-bound, single-use ceremony step.

Expiry and consumption are decided on the database clock.

Properties as follows:

  • id:
  • purpose:
  • browser_nonce_hash:
  • challenge_hash: SHA-256 hex of the challenge issued for this ceremony: every ceremony is bound to one.
  • created_at:
  • expires_at:
  • consumed_at:
  • user_id

    1631 PR2: a REGISTER ceremony's binding, set once at its options step (cor:aut:040:02): who registers,

    'first' (a fresh sign-in, its method and that browser's hash) or 'later' (the vouching passkey), and the fresh random WebAuthn user handle. Null for every other ceremony.

  • kind:
  • registration_method:
  • sign_in_browser_hash:
  • vouch_passkey_id:
  • user_handle:

passkey_registration_notices

1631 PR2 (cor:aut:040:02): every registration's email notice, written in the registering transaction and sent

by a loop. A first passkey's carries its cancel token encrypted until sent. seenAt records the in-app notice.

Properties as follows:

  • id:
  • passkey_id:
  • user_id:
  • kind: 'first' | 'later'
  • cancel_token_enc:
  • created_at:
  • attempts:
  • lease_until:
  • claim_token:
  • sent_at:
  • failed_at:
  • seen_at:

passkey_cancel_tokens

1631 PR2 (cor:aut:040:07-08): a first passkey's cancel link. One per first passkey, stored as SHA-256,

spent once, never deleted; the cancel itself is recorded on the credential. Times come from the guard trigger.

Properties as follows:

  • id:
  • passkey_id:
  • token_hash:
  • created_at:
  • used_at:

fresh_sign_ins

1631 PR1b slice 2 (cor:aut:040:09): a fresh sign-in bound to the ceremony browser. Signs the person in to

nothing. Counts once confirmed by the same browser, and is consumed once. Times are set by the guard trigger from the database clock; identity is immutable. Rows are disposable after 24 hours.

Properties as follows:

  • id:
  • user_id:
  • method: 'github' | 'google' | 'apple' | 'email', set from the provider whose callback ran.
  • browser_nonce_hash:
  • leg_hash: SHA-256 of the one-time leg id (IdP) or emailed token (email). The raw value is never stored.
  • created_at:
  • expires_at:
  • signed_in_at:
  • confirmed_at:
  • consumed_at:
  • consumed_for: 'register' | 'end-window' | 'revoke'

pending_email_sign_ins

1897 slice B1: an email sign-in waiting for its passkey. Created when a magic link is claimed for a user who

has a passkey, and completed only by that passkey's assertion over a SIGN_IN ceremony bound to this browser. Publishes nothing: no handoff code, no JWT, no cookie, no key exists until it completes. Identity and continuation are immutable; completion is set once, together with the sign-in it produced.

Properties as follows:

  • id:
  • user_id:
  • continuation: 'PORTAL' | 'OAUTH'. Each kind carries exactly its own columns (CHECK).
  • client_state_hash: Portal: the ORIGINAL SHA-256 of the requesting browser's nonce, carried untouched to the handoff code.
  • redirect:
  • is_new:
  • return_to: OAuth: the already-validated server-local path to resume at.
  • browser_hash: SHA-256 of the pending cookie; the cookie value is never stored.
  • ceremony_id: The current SIGN_IN ceremony; replacing it consumes the earlier one.
  • created_at:
  • expires_at:
  • completed_at:
  • sign_in_id:

passkey_credentials

1631 schema-first: shared credential registry (cor:aut:040:05), no enrollment route yet.

Identity/public-key fields are immutable; records are never deleted, revokedAt is set once.

Properties as follows:

  • id:
  • owner_id:
  • credential_id: Raw WebAuthn identifier bytes: encoding aliases cannot create duplicate records.
  • public_key:
  • algorithm:
  • user_handle: Random authenticator user handle, not an email, User.id or session bearer.
  • enrollment_rp_id

    The WebAuthn RP ID the credential was registered under (Eden #10470), recorded at enrollment and immutable. Never inferred from the current PASSKEY_RP_ID: an assertion counts only while it equals the deployment's RP ID (cor:aut:040:06).

  • label:
  • registered_at:
  • last_used_at:
  • revoked_at:
  • counter: WebAuthn's unsigned 32-bit counter does not fit a signed PostgreSQL Int.
  • transports:
  • backup_eligible:
  • backed_up:
  • registration_method: First credential only: the verified sign-in method used for registration.
  • window_ends_at:
  • window_ended_at:
  • window_outcome: null while open (or not first); ran-out | ended-early | cancelled once closed.
  • cancelled_at: SEC-9: provenance of a cancel-link use, distinct from other revocation routes.
  • cancel_ip:
  • cancel_user_agent:

user_api_key_deletions

2659 (hrn:node:hadronmemory.com:specs:cor:dmo:070:03, ruling 0007 A): the one append-only trace of a user

deleting one of their own API keys. Who (the key's own user: ruling 0006 lets no one else delete it), which key (its id and masked preview) and when; never its secret or its hash. revokedKeyIds names the keys the delete itself revoked (the key when live, and its live subtree, cor:aut:010:02 rule 9); mintedKeyIds names the keys it had minted, whose link to it broke (ruling 0005 B: they stay, revoked, with no parent). No FK to the key: it is gone. Never updated, and never deleted while its user row exists (prisma/user-api-key-deletion-invariants.sql).

Properties as follows:

  • id:
  • user_id:
  • key_id:
  • key_preview:
  • revoked_key_ids:
  • minted_key_ids:
  • deleted_at:

sign_ins

1897 / cor:aut:030:02 + R66: a completed, factor-protected sign-in. Its id is

the sid claim of the JWT it publishes and the root of every code/key that descends from it, so ending it (the first-passkey cancel link) can revoke exactly that lineage. Identity/lineage fields are immutable; only endedAt/ endReason are set, once. Rows are never deleted while descendants exist.

Properties as follows:

  • id:
  • user_id:
  • method: How the person arrived ('email'); the factor is completedByPasskeyId.
  • completed_by_passkey_id:
  • completed_at:
  • expires_at:
  • ended_at:
  • end_reason:

signing_requests

1632 / cor:dmo:130:03 — a request for a person to sign one node's content.

Pinned at creation and immutable: the node, its revision, the v1 approval hash and the payload version. It is open, then ends exactly once: completed | declined | expired | stale | withdrawn. Ended requests are kept for the node's lifetime (#10019). Every timestamp comes from the DB clock, set by the guard trigger (prisma/signing-invariants.sql), which also enforces the single end; application code only names the end state. User / App / worker ids are sealed history with no FK (an FK action would be a write the guard refuses): see conventions:append-only-table-trigger.

Properties as follows:

  • id: 128 bits of randomness, base64url (plan SEC-8): never guessable.
  • node_id:
  • revision:
  • approval_hash:
  • payload_version:
  • named_signer_id: Null = any eligible signer (a writer of the node's memory).
  • requester_user_id: The requester ACCOUNT is requesterUserId, else requesterAppId (#10397).
  • requester_app_id:
  • requester_worker_id:
  • requester_session_id:
  • state: open | completed | declined | expired | stale | withdrawn
  • created_at:
  • expires_at:
  • ended_at:

node_signatures

1632 / cor:dmo:130:07 — an append-only signature record: no update or

delete surface at all (cor:dmo:130:05). Removed only with its node (hard delete, memory delete). State is never stored; it is derived on every read by re-verifying the stored assertion (src/lib/signing/state.ts).

Properties as follows:

  • id:
  • node_id:
  • signing_request_id: The request it completed; one record per request.
  • signer_id: A person, always. Sealed history: no FK.
  • passkey_credential_id:
  • revision:
  • approval_hash:
  • payload_version:
  • rp_id

    The WebAuthn RP ID the signature was made under, from config at completion. Re-verification uses this, never the current PASSKEY_RP_ID, so a domain change cannot invalidate old signatures (#10469/#10470). The guard requires the assertion's rpIdHash to match it.

  • authenticator_data:
  • client_data_json:
  • signature:
  • verified_at:

auth_handoff_codes

Short-lived, single-use handoff codes that keep the session JWT out of browser-visible URLs (#477). Two kinds share the same shape: - 'login' — minted after GitHub/email auth; the portal's server load redeems it at POST /auth/session for the JWT, which it sets as an HttpOnly cookie. For the GitHub flow clientStateHash binds the finishing browser to the login it started (session-fixation defense); the email flow leaves it null (magic links open cross-device). - 'exchange_start' — minted by POST /auth/microsoft/start (Bearer-authed, server-to-server) so the long-lived JWT never rides in the /auth/microsoft redirect URL. The raw code is only ever handed out once; the DB stores its SHA-256 hash. Single use is enforced by an atomic updateMany(redeemedAt: null) claim, mirroring AuthCode. DB-backed (not in-memory) so it survives multi-worker deploys, unlike the legacy pendingStates maps.

Properties as follows:

  • id:
  • code_hash: SHA-256 hash of the raw code handed to the browser/portal.
  • kind: 'login' | 'exchange_start'.
  • user_id:
  • redirect: Post-redemption destination path (login: portal path; exchange: return path).
  • is_new: login only — whether the user was just provisioned (drives /app/setup).
  • login_evidence: Verified login evidence survives handoff; redemption must never refresh it.
  • org_id: exchange_start only — the org the Exchange connection is being attached to.
  • client_state_hash

    login+GitHub only — SHA-256 of the portal-set browser nonce; the redeemer must present the matching raw nonce (constant-time compared).

  • expires_at:
  • redeemed_at:
  • created_at:
  • sign_in_id: #1897: the sign-in this handoff publishes (null = not factor-protected).
  • flow_id: #2913: exchange_start (GraphQL origin) only — the ConnectionFlow this nonce belongs to. No FK: the flow outlives the nonce.

pending_login_states

Durable pending login state for the first-party auth flows (GitHub / Google / Apple, src/auth/pendingLoginState.ts). Carries the OAuth state-CSRF token minted at the start route until the provider callback claims it (atomic delete-by-PK — single use). Replaces the three in-process pendingStates Maps in server.ts, which died on every deploy/restart: the provider callback then 400d mid-login — the failure mode behind the Apple App Review "the app failed to login with Apple" rejection (Apple's callback is a cross-site form POST after a flow that can involve slow 2FA). DB-backed rows survive restarts and multi-worker deploys. No user FK: the row exists BEFORE we know who is logging in.

Properties as follows:

  • state

    The OAuth state CSRF token (random hex) — handed to the IdP at the start route and echoed back on the callback.

  • provider

    'github' | 'google' | 'apple' — a state minted for one provider can never be claimed by another provider's callback.

  • redirect: Portal-local path to land on after login (portal-handoff flow).
  • return_to: Spec 025 FR-007 Option-C server-local return path (cookie flow).
  • client_state

    477 session-fixation binding — the portal's browser nonce, stamped

    onto the login handoff code at the callback.

  • ceremony_nonce_hash

    1631 PR1b: SHA-256 of the ceremony browser cookie when this state is a passkey ceremony's sign-in leg.

    Such a state carries no return_to or client_state (CHECK), and its callback mints no session.

  • provider_nonce_hash

    2204: SHA-256 of the OIDC nonce sent to Google/Apple (binds the ID token to this attempt). NULL only for

    GitHub and for rows minted before #2204; chk_pending_login_provider_nonce (NOT VALID) refuses a new google/apple row without it. Distinct from client_state and ceremony_nonce_hash, which bind the browser.

  • expires_at:
  • created_at:

app_runs

One headless run (cor:agt:010:02). Simultaneously the audit record AND — v1, D-2026-07-04-D — the activation: created only after the launch gate passes; every action inside the run re-checks status + policy and decrements the live budgets; zeroing a budget or setting CANCELLED halts the run at its next action (the kill switch). Also the outbox row for run.requested.v1 (publishedAt NULL ⇒ sweep republishes).

Properties as follows:

  • id:
  • organization_id:
  • app_id:
  • agent_id:
  • user_id

    On-behalf-of user (cor:agt:010:01, D-2026-07-04-C). NULL ⇒ pure App service identity — no personal/private reach.

  • trigger_kind:
  • trigger_id:
  • automation_pin: #1719 R5b: owner-adopted complete graph; NULL fails closed at execution.
  • entry_node_urn:
  • entry_node_id

    2438: the entry node's stable id — what the run resolves by once the

    automation pin moved off literal URNs. NULL on runs minted before the column existed; those keep verifying under their stored pin's URN identity.

  • event_data:
  • data

    Run envelope (D-2026-05-09-013): the mutable bag of fields extracted by flow nodes as the walker advances. Bare field names — conditions address them through the evaluator's message.data.* scope prefix (plan-multi-node D-MN-1). eventData stays the immutable trigger payload; on key collision the envelope wins.

  • hops

    Per-hop trail (#538): the walked path, one element per COMPLETED hop, appended in the same checkpoint/finish UPDATE the runner already writes. [{node, edgeOut, startedAt, finishedAt, tokensSpent}] — edgeOut is the routing edge taken FROM the hop (null on the last). Bounded by RUN_MAX_HOPS. A hop that FAILS mid-execution has no element; curNodeUrn + failure identify it.

  • derived_log

    2047 (S10, cor:agt:040:03): the derived blocks each hop of the run saw, append-only, [{hop, blocks}], where

    blocks is the full list and may be EMPTY (so a block going away is recorded too). An entry is written, guarded on RUNNING, before the hop's LLM call and only when the blocks differ from the last entry, so a hop that fails or is aborted (it gets no hops element) still shows what it saw. The blocks seen by hop n are the last entry with hop <= n. Run progress, readable by the run read gate; deliberately NOT part of the immutable boot record.

  • spawn

    PARENT-side fan-out state (plan-spawn D-SP-1): set by hadron_spawn — {processItem, itemKey, callback?, itemCallback?, total, dispatching?, callbackFiredAt?}. Its own column, NOT data: the parent's envelope checkpoint would clobber a mid-hop write there. callbackFiredAt is the exactly-once claim (D-SP-4, atomic SQL).

  • policy: Run-layer allow-list snapshot (the narrowest chain link; plan §4).
  • budget_tokens: Remaining LLM tokens — live-decrement kill switch.
  • budget_actions: Remaining tool/write actions — live-decrement kill switch.
  • budget_tokens_initial

    832 — the budget this run was MINTED with, so a client can render

    "spent vs budget". budgetTokens above is what REMAINS. NULL on runs minted before the column existed.

  • budget_actions_initial:
  • tokens_spent

    832 — cumulative spend, incremented in the same write as the budget

    decrement. Deliberately NOT derived: * a hops sum under-reports — a hop that failed mid-execution has no element, which is exactly the run an operator is auditing; * initial - remaining under-reports too — the decrement is CLAMPED (Math.min(spent, budget)) so the remaining budget never goes negative, and an overspending run would report exactly its budget. These counters are unclamped and therefore truthful in overage.

    NULLABLE with a default: new runs start at 0, while a run minted BEFORE the columns existed is genuinely UNKNOWN rather than zero — reporting 0 for a run whose already-decremented budget proves otherwise would be a false total (PR #854 review, Codex P2). tokens_spent is backfilled from the hop trail where one exists; actions_spent has no such signal.

    A rejected tool-loop call counts the steps the SDK had already completed (#862); usage the SDK did not report (the failed step, or a step without counts) is not counted, so such a run can still under-report. See the GraphQL field docs.

  • actions_spent:
  • cost_micro_cents

    2439 — priced LLM cost of this run in micro-cents (1e-8 USD): the sum of

    its usage events' costMicroCents, incremented where each event is recorded. Unpriced events add nothing. NULL = UNKNOWN for a run minted before the column existed (no usage-event link to back-fill from); new runs start at 0.

  • status:
  • cur_node_urn:
  • scope_snapshot

    Spec 049 Phase 3b (D-2026-09-13-004): the trigger's scope, SNAPSHOTTED at mint as its ordered memory-id list (as policy is snapshotted — a run must not change meaning because someone edited a scope mid-flight). SCOPE DATA ONLY: every consumer re-intersects it with the principal's CURRENT access (resolveRunScope); never an access grant that outlives a revoked membership. NULL ⇒ app.

  • register_snapshot

    Spec 049 Phase 6 (D-2026-09-13-007): the attendee's resolved REGISTER at mint (Agent-in-App = agentId + appId), rows only — for the attention section (Phase 7). Same re-intersection rule as scopeSnapshot: the Channel watermarks are read live and the gates are evaluated on every use; never a grant. NULL ⇒ no attendee.

  • parent_run_id:
  • failure:
  • timeout_ms:
  • attempts:
  • published_at:
  • started_at:
  • finished_at:
  • created_at:
  • created_by:

agent_schedules

Recurring trigger (cor:agt:010, D-2026-07-04-E) — per-kind table mirroring the decided AgentWebhook shape. The scheduler claims rows by (enabled, nextRunAt) and mints an AppRun per due tick.

Properties as follows:

  • id:
  • organization_id:
  • app_id:
  • agent_id:
  • user_id: On-behalf-of user, captured at creation (cor:agt:010:01).
  • name:
  • cron

    5-field cron expression, evaluated in timezone — recurring schedules. XOR with runAt (chk_agent_schedule_cron_xor_run_at).

  • timezone:
  • run_at

    One-shot: run once at this instant (#510). XOR with cron; the scheduler claim flips enabled to false instead of advancing nextRunAt. Misfire policy unchanged (overdue runs once).

  • automation_pin: #1719 R5b: owner-adopted complete graph; NULL fails closed at execution.
  • entry_node_urn:
  • entry_node_id

    2438: the entry node's stable id, stamped at adoption (and lazily at

    launch) — a same-memory rename/move of the entry keeps the trigger working; entryNodeUrn stays the immutable display/audit address.

  • budget_tokens: #2479: optional per-run limits; NULL uses the current platform default.
  • budget_actions:
  • event_data:
  • policy: Trigger-layer allow-list (chain link; plan §4).
  • ai_config_name: Per-trigger AI-config override (name into the spec-036 walk).
  • scope_id: Spec 049 Phase 3b (D-2026-09-13-004) — the scope this trigger's runs carry, snapshotted at mint; NULL ⇒ app.
  • enabled:
  • last_run_at:
  • next_run_at

    Next due time — the scheduler's work signal. A skipped overlap STILL advances this (plan §7; prevents back-to-back storms).

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

quota_counters

Continuous quota tier (cor:acl:050:01/:04): windowed counters per App and per org for run.execute + llm.tokens. Checked at the launch gate and decremented live during runs.

Properties as follows:

  • id:
  • scope_kind:
  • scope_id:
  • action:
  • window:
  • used:
  • limit:
  • reset_at:

action_tickets

Consumable quota tier (cor:acl:050:01/:04): TAN-style tickets, v1 required only for the outbound-communication action class. The ledger answers "where did they all go?" — every consumption names the run.

Properties as follows:

  • id:
  • organization_id:
  • app_id:
  • action:
  • minted_by:
  • note:
  • consumed_by_run_id:
  • consumed_at:
  • expires_at:
  • created_at:

ai_model_prices

Provider price row for one (provider, model, tier) triple — the rate source for UsageEvent.costMicroCents AND the debit markup (spec 046 FR-002/FR-003). Effective-dated: lookup takes the latest effectiveAt <= eventTime with deletedAt IS NULL; price changes append a new row, never mutate an old one (historical costs stay auditable — stamped costs are snapshots, so soft-deleting a mispriced row is safe and is the "retire" lever). Prices are in micro-cents (1e-8 USD) per MILLION tokens — e.g. $3/MTok input = 30_000_000. Operator-managed via setAiModelPrice (platform admin); an absent triple means "no cost computed", never a blocked call. String columns, no enums — validation lives in src/lib/metering.

Properties as follows:

  • id:
  • provider:
  • model:
  • tier

    Pricing tier 1-3 (Holger, 2026-07-11): reserved room for future product tiers carrying different markups per (provider, model) WITHOUT another AiModelPrice migration. Everything defaults to and resolves tier 1 until tiers become a real product concept; the semantics of 2/3 are deliberately undefined today. Validated 1-3 in code (setAiModelPrice / getAiModelPrice), no CHECK by convention.

  • input_micro_cents_per_mtok: Micro-cents per 1M input tokens.
  • output_micro_cents_per_mtok: Micro-cents per 1M output tokens.
  • markup_basis_points

    Markup applied when debiting platform-key spend at THIS tier, in basis points (2500 = 25%) — integer-exact, no float money. NULL falls back to the CREDIT_MARKUP_PERCENT env (which this column supersedes). Effective-dated with the rest of the row.

  • effective_at: Row applies to events at/after this instant (until a later row).
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

credit_ledger_entries

Append-only monetary ledger for an organization's AI credits (spec 046 FR-005). Signed amounts: grants +, debits −, adjustments ±; balance is SUM(amountMicroCents). Rows are NEVER mutated, deleted, or reset — this is the durable billing record (unlike QuotaCounter's daily counters). expiresAt on grants is stored policy only in Phase 0 (jurisdictions restrict prepaid expiry — see the spec's legal notes); FIFO expiry enforcement is a later phase. Automatic usage debits are gated by BILLING_DEBIT_ENABLED and apply only to platform-key spend (FR-004/006). Audit columns follow the schema-wide convention; the SANCTIONED correction is an adjustment row — soft-delete is break-glass ops only (balance and reads exclude soft-deleted rows, codebase-wide semantic).

Properties as follows:

  • id:
  • organization_id:
  • kind: 'grant' | 'debit' | 'adjustment' (validated in src/lib/metering).
  • amount_micro_cents: Signed micro-cents (1e-8 USD). Grants positive, debits negative.
  • expires_at: Grant expiry policy field (no enforcement in Phase 0).
  • source_type

    Provenance: e.g. ('usage-event', <UsageEvent.id>), ('admin', <userId>), later ('payment', <processor ref>).

  • source_id:
  • note:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

agent_webhooks

Webhook trigger (D-2026-05-02, spec 040 plan §8) — per-kind table like AgentSchedule. URL shape: /hooks/<secret>/<name>?hpt=<platform JWT>. The opaque secret is the lookup key (no app/agent IDs in the URL); the time-limited platform JWT is the second factor — a leaked URL is useless without it (D-2026-05-02-006).

Properties as follows:

  • id:
  • organization_id:
  • app_id:
  • agent_id:
  • user_id: On-behalf-of user, captured at creation (cor:agt:010:01).
  • name:
  • secret: Opaque URL secret — unique lookup key, never reused across webhooks.
  • args_schema: JSON Schema for POST args (stored in v1; Ajv enforcement is follow-on).
  • automation_pin: #1719 R5b: owner-adopted complete graph; NULL fails closed at execution.
  • entry_node_urn:
  • entry_node_id

    2438: the entry node's stable id, stamped at adoption (and lazily at

    launch) — a same-memory rename/move of the entry keeps the trigger working; entryNodeUrn stays the immutable display/audit address.

  • budget_tokens: #2479: optional per-run limits; NULL uses the current platform default.
  • budget_actions:
  • event_data:
  • policy:
  • ai_config_name:
  • scope_id: Spec 049 Phase 3b (D-2026-09-13-004) — the scope this trigger's runs carry, snapshotted at mint; NULL ⇒ app.
  • enabled:
  • last_called_at:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

mcp_session_state

1012 — a client's DURABLE MCP selections (active App, active memory).

The in-process selection maps in src/mcp/server.ts live for exactly one MCP TRANSPORT session, and clients re-initialize transparently after a server restart — so a selection silently evaporated mid-conversation (#1005). #1009 made that loss legible and recoverable for callers holding a Hadron session id; this table is the remedy for everyone else, including plain memory work with no session at all.

Keyed on (userId, clientKey), NOT on the MCP session id — which is exactly the thing that does not survive. clientKey is the caller's own stable instance id, supplied per request via the X-Hadron-Client-Id header. A client that sends none is not persisted at all and keeps the pre-#1012 in-memory behaviour, so nothing regresses for clients that never opt in.

Per-CLIENT rather than per-USER on purpose: one person may drive Claude Desktop, Cursor and the CLI at once, and a per-user row would let one switch the others' active App mid-conversation — turning a lost selection into a silently wrong one, which is worse than the bug being fixed.

This is a CACHE of a choice, never a grant. Both pointers are re-authorized on read (isAppParticipant for the App, the memory read gate for the memory), because a stored selection outlives the membership that justified it (#475 / the #1007 review finding). Both are nullable and SetNull, so a deleted App or memory degrades to "nothing selected" rather than dangling.

Properties as follows:

  • id:
  • user_id:
  • client_key

    Caller-supplied stable client-instance id (X-Hadron-Client-Id). Opaque to the server; length-capped and trimmed at the boundary.

  • app_id: The active App selection, or NULL if none. Re-authorized on every read.
  • memory_id

    The active memory selection, stored as the PK rather than the URN so a rename cannot strand it. The URN is resolved on read.

  • organization_id

    Spec 049 Phase 1 (D-2026-09-13-003) — the EXPLICITLY selected active organization (hadron_set_active_org), or NULL if none. Distinct from the App's organization, which is derived from appId at read time and outranks this in the resolution ladder (src/lib/auth/activeOrg.ts). Re-authorized against current org membership on every read — a stored selection is a cache of a choice, never a grant.

  • scope_id

    Spec 049 Phase 3 (D-2026-09-13-002) — the session's ACTIVE SCOPE (hadron_set_active_scope): rung 2 of the search ladder, outranked only by a scope named in the call. Re-authorized (readable) on every read.

  • created_at:
  • updated_at:

urn_aliases

1079 — every URN an entity USED to answer to.

A URN is the platform's stable, publishable identifier: it goes into commit trailers, PR descriptions, issue signatures, chat messages and exported documents, none of which can be rewritten after the fact. Four entities store their URN in a column, and all four can be renamed; a node's composed URN also changes when its loc or memory changes. Without this table those changes silently turned published references into a 404.

The blast radius is wider than the four rows, because most URNs in the platform are COMPOSED on read from one of them: a node URN carries its memory's slug, a worker URN carries its App's slug, an apprun URN likewise. Renaming one memory therefore orphans every published node URN under it. Aliasing the four storing entities heals parent renames. A node move also records the old composed node URN, because its loc or memory can change while both stored parent URNs remain unchanged (#1391).

Liveness is not stored here. A row records only that a URN once addressed an entity; whether that entity is still readable, uninstalled or soft-deleted is answered by re-querying it, so an alias can never resurrect a dead row or leak one past its own gate.

A live URN always wins. An old URN becomes free on rename and may be taken by a new entity, so every resolver tries the urn column first and consults this table only on a miss. Two entities may therefore legitimately have held the SAME urn at different times; that is why the alias urn is not unique, and an ambiguous lookup fails loudly rather than guessing (the AmbiguousLegacyUrnError rule this shares with the legacy_urn fallback).

Properties as follows:

  • id:
  • urn

    The superseded URN, stored in the same normalized lookup form the resolvers compute (hrn:/urn: prefix stripped, :: collapsed to :) — a raw spelling here would be unreachable from a normalized query.

  • entity_type:
  • entity_id:
  • reason:
  • replaced_by_urn

    The URN that replaced it — provenance only, never matched on. Null for a V1_MIGRATION backfill row, whose successor is the entity's current urn.

  • created_at:
  • created_by: Who performed the rename, when a principal was attributable.

scopes

Spec 049 Phase 2 (D-2026-09-13-001) — a named search SCOPE ("lens"): an ORDERED list of memories with exactly one owner — organization, Agent, or App — as three nullable FKs with a CHECK (chk_scope_owner, num_nonnulls(...) = 1), never an ownerKind string. The Scope pattern the register table copies (plan §2 S1). A scope selects memories only (filters stay per call; no saved filter, no retrieval parameters) and NEVER grants: every consumer intersects it with the caller's accessible set (D-2026-09-13-004, lib/auth/narrowToAccessible.ts).

name is unique PER OWNER among live rows — partial unique indexes in post-push.sql / the migration, since Prisma cannot express them and a plain @@unique would let a soft-deleted row block the name forever. Collisions across owners in an App's context resolve App › Agent › organization, namespaced, never unioned (lib/scopes.ts). global and app are reserved ladder tokens and refused at create.

Properties as follows:

  • id:
  • name:
  • description:
  • organization_id:
  • agent_id:
  • app_id:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

scope_memories

The ordered memory list of a Scope. A join row rather than an id array so that "which scopes include this memory" is a query (D-2026-09-13-001 rejected ids-in-JSON for exactly that — scope explain and memory deletion need the reverse lookup) and so a deleted memory cascades out of every scope. Composite PK: listed in MODELS_WITHOUT_ID (db/client.ts).

Properties as follows:

  • scope_id:
  • memory_id:
  • position

    0-based order within the scope — the only thing the task-customization operation will consume; search ignores it (D-2026-09-13-005).

channels

Spec 049 Phase 4 (D-2026-09-13-006) — a CHANNEL: a durable, ordered message stream hosted in ONE memory at ONE reserved address, server-ordered and server-attributed, that people and Agents post to and an Agent can be told about. NOT a chatbot conversation (cor:cht). A PLATFORM ENTITY, not the chat-root node: the row is created EAGERLY, one-to-one with its chat root (chatRootNodeId, unique), in the same transaction — that is what makes "the canonical reference is the PK of the chat node" and the table one thing, and what leaves nothing unprotected before the first post.

Creating a row RESERVES and PROTECTS its address: every generic node write under loc (and any subtree operation overlapping it) is refused (src/lib/protectedLoc.ts, spec 049 §2 S4 shape B). The Channel table is the protection's ONLY source: D-2026-08-25-004 added Memory.protectedLocs as a second one and #1201 removed it again — governance of authored kinds moved to Node.role + isRunnable, a property of the WRITE rather than of the address. ADDRESS-based protection is a Channel concept and only that. The owning operations write through their own gate. This is hadron-server#1047's closure: the loc is operation-exclusive because it is protected, and protected because this row declared it.

lastSeq / lastMessageAt are the platform-maintained WATERMARK (D-2026-09-13-009) — the allocator's output, written inside appendChatMessage's lock in the same transaction as the seq. The chat root's data.messageCount stays what it is, a routing operand; two numbers, two jobs. lastSeq − lastSeenSeq is a watermark delta, never a message count (gaps and the known prod duplicate are preserved).

Reusing a soft-deleted Channel address tombstones its old transcript and resets these Channel watermarks to the empty state, but preserves the root allocator history. The first new post therefore resumes above the old seq maximum, which prevents a retained read cursor from hiding that message.

The audience is the HOST MEMORY's (cor:acl:030:01): a Channel has no access layer of its own. Participation, reads and posts follow the memory. Soft-deleted in step with its root; the protection holds while either exists.

Properties as follows:

  • id:
  • memory_id:
  • loc: The reserved address of the chat root (e.g. chats:team).
  • name:
  • kind:
  • description:
  • chat_root_node_id:
  • last_seq:
  • last_message_at:
  • incarnation

    Monotonic identity of the live occupancy at this reserved address. Incremented when a tombstoned Channel is reused so requests resolved against the previous incarnation cannot post to or delete the new one.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

register_entries

Spec 049 Phase 5 — a REGISTER ENTRY (D-2026-09-13-007, §14 corrections 1 and 2): "this attendee takes part in this Channel". Owned by exactly ONE of an organization or an App (S1: chk_register_owner). The attendee is a Worker when cast, otherwise an Agent in an App; BOTH NULL means every attendee in the owner's context (org-wide for an org row, App-wide for an App row) — one row for "every Agent attends the announcements channel".

Not a trigger list: a row here never starts a run. Not exportable (D-2026-08-25-006): platform instrumentation, excluded from memory export and the git mirror. The register never grants — canRead / canPost are the host memory's gates, evaluated at read time (Phase 6).

Partial uniques per (owner, channel, attendee) WHERE deleted_at IS NULL — the install default's natural key (post-push.sql, the migration).

Properties as follows:

  • id:
  • organization_id:
  • app_id:
  • channel_id:
  • attendee_worker_id:
  • attendee_agent_id:
  • role:
  • mention_only:
  • description: The human's intent, free text (D1).
  • install_default

    D2 — the row install materialised for the App's default Channel; an App may remove it (D4), uninstall removes it.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

channel_read_states

Spec 049 Phase 7 — per ATTENDEE per Channel: where this attendee is up to (D-2026-09-13-009, §14 correction 1). OUTSIDE the register: a cursor on the register row "mixes what-I-attend with where-I-am and the relay would keep a second copy". Keyed on the attendee, not the bare Agent — two Workers cast from one Agent in one App must not share a cursor. Advances are MONOTONIC (GREATEST, lib/channelReadState.ts): an older transaction never overwrites a newer cursor; concurrent runs may both see a window as new — duplicate attention, never skipped attention. Mute is session state, never a column here (D16 local).

CHECKs chk_read_state_attendee (exactly one of worker / agent) and chk_read_state_agent_app (an Agent attendee carries its App); partial uniques on (worker, channel) and (agent, app, channel) — post-push.sql.

Properties as follows:

  • id:
  • worker_id:
  • agent_id:
  • app_id:
  • channel_id:
  • last_seen_seq:
  • updated_at:
  • last_checked_at

    2138 §3.1 — when the worker last CHECKED this channel through its own bound session (a page read, an

    inbox read or a mark-read, an empty one included). Stamped only by stampChannelCheck; a read by a person (asMe), by another worker or of another channel never moves it. NULL = never checked.

  • channel_incarnation

    2181 — the Channel incarnation the stored cursor was last RAISED under. Written by advanceReadState in the

    same statement that creates the row or raises lastSeenSeq (an equal or lower mark changes neither). NULL = legacy or never advanced under a known incarnation; it is never backfilled and never relabelled, so a stale cursor is not presented as current.

memory_configs

A memory's complete rulebook: exactly one per memory, by construction. memoryId @unique makes it at most one; an ABSENT row reads as the empty config, so every memory has one without a backfill or a creation hook, and the first rule write materializes it. Not shared between memories — templates are the shared, owned thing, and they are COPIED in (Holger, 2026-09-25, #1325 H4). Read and managed only by the memory's managers; enforcement loads it internally for any writer.

Properties as follows:

  • id:
  • memory_id:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

node_role_rules

One row per role or dotted sub-role (spec, spec.rule): the rows ARE the config's declared roles, and a row may carry no tasks at all (#1325 H1). strictSubRoles on a parent row refuses its undeclared sub-roles; off, an undeclared sub-role falls back to the nearest declared ancestor (#1322's lookup).

Task references are node-id FKs — accepted and shown as URNs — so moving a task keeps the rule (moveNode keeps ids, even across memories). A HARD delete of the task (replaceSubtree, git sync of a removed file, memory deletion) nulls the FK; the *TaskRequired marker survives it, so the rule FAILS CLOSED instead of silently ceasing to require the task (#1325 H5). Cascade and Restrict were rejected: the first drops governance, the second lets whoever references a public task veto its owner's own deletes.

Properties as follows:

  • id:
  • config_id:
  • role:
  • author_task_id:
  • author_task_required:
  • validation_task_id:
  • validation_task_required:
  • description_node_id:
  • strict_sub_roles:
  • writers:
  • validate_by:
  • enabled:
  • source_template_id

    1334 — the template this rule was copied from. Provenance only, no FK:

    a template is copied in, never live-linked, so deleting one must not rewrite the configs it was applied to.

  • locked: #1334 — set by a REQUIRED template; only org admins may change the rule.
  • revision

    Optimistic-concurrency counter (#1325, cli#716 Q1): starts at 1, +1 on every update; a mutation passing expectedRevision refuses CONFLICT when it no longer matches, so a stale read can never overwrite a newer write.

  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

memory_config_templates

A reusable rulebook owned by EXACTLY ONE of HadronServer / Organization / User / App — nullable FKs with a CHECK (chk_memory_config_template_owner, num_nonnulls(...) = 1), never an owner-kind string (the Scope / AiServiceConfig mechanism, plus a User owner AiServiceConfig does not have). Applied by COPYING its rules into a memory's config (#1334); editing a template changes no memory until it is re-applied. required templates arrive locked. name is unique per owner among live rows (partial unique indexes in post-push.sql / the migration).

Properties as follows:

  • id:
  • name:
  • description:
  • required:
  • revision

    Optimistic-concurrency counter, as on NodeRoleRule. Rules are replaced wholesale with the template, so the template's revision covers them.

  • hadron_server_id:
  • organization_id:
  • owner_user_id:
  • app_id:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

memory_config_template_rules

A template's rule: NodeRoleRule's columns minus the per-memory provenance and lock, with the same node-id FK + fail-closed marker semantics.

Properties as follows:

  • id:
  • template_id:
  • role:
  • author_task_id:
  • author_task_required:
  • validation_task_id:
  • validation_task_required:
  • description_node_id:
  • strict_sub_roles:
  • writers:
  • validate_by:
  • enabled:

automation_adoption_events

2441 — append-only record of every approval, decline and revocation of an

automation's consent (cor:agt:010:01). Written in the SAME transaction as the pin change by adoptionDoor (resolvers.automationPin.ts) and nowhere else. The trigger id, the actor and the org carry no FK on purpose: history must survive trigger deletion and user erasure, and an FK action would have to UPDATE a row the trigger refuses to update. The App FK cascades so a hard delete still works (the trigger lets a DELETE through once the App is gone).

Properties as follows:

  • id:
  • app_id:
  • organization_id: The App's organization; null for a user-owned App.
  • trigger_kind: SCHEDULE | WEBHOOK | MANUAL (CHECK in automation-adoption-invariants.sql).
  • trigger_ref: The trigger row id; for MANUAL, the origin run id. Plain text, no FK.
  • action: APPROVE | DECLINE | REVOKE (CHECK).
  • actor_user_id:
  • pin_hash

    APPROVE: the adopted hash. REVOKE: the hash of the removed pin. DECLINE with nothing adopted: null.

  • created_at:

app_memory_write_grants

2484 (cor:agt:010:01, epic #2435) — an App's write grant on ONE memory under ONE loc prefix, for its USERLESS

runs only: the register-recorded grant the Open paragraph rules on. One row per (App, memory, prefix); the prefix is required and matches the loc itself and its :-boundary descendants only, judged on the destination after writeTo expansion, at write time (src/lib/appWriteGrant.ts). A row is never edited: it ends with a terminal revokedAt (trigger + CHECKs in app-memory-write-grant-invariants.sql, where the partial unique index also lives). grantedBy / revokedBy carry no FK on purpose: they are sealed history of who acted and must survive user erasure. registerNodeUrn is a citation of the register line, never evidence that the line exists.

Properties as follows:

  • id:
  • app_id:
  • memory_id:
  • prefix:
  • register_node_urn:
  • granted_by:
  • created_at:
  • revoked_at:
  • revoked_by:

app_memory_write_grant_events

2484 — append-only record of every grant and revocation of an App memory write grant: who, which App, which

memory, which prefix, and nothing of any node's content. Written in the SAME transaction as the row change by src/lib/appWriteGrant.ts and nowhere else. The memory, grant and actor carry no FK on purpose: history must survive their deletion. The App FK cascades so a hard delete still works (the trigger lets a DELETE through once the App is gone).

Properties as follows:

  • id:
  • app_id:
  • memory_id:
  • grant_id:
  • prefix:
  • action: GRANT | REVOKE (CHECK in app-memory-write-grant-invariants.sql).
  • actor_user_id:
  • created_at:

app_automation_read_grants

2883 (ruling 0081 = A; cor:agt:010:01 read-grant rule) — an automation's READ grant on ONE memory, optionally under

one loc prefix (a NULL prefix is the whole memory). "The automation" is the TRIGGER ROW a run executes (AgentSchedule / AgentWebhook, keyed (appId, triggerKind, triggerId)); the key carries across an edit and a re-adoption, and the grant ends on revoke or when the trigger is soft-deleted (judged live at the read: no FK, the trigger is polymorphic). Read-only, consulted only by the run hadron_read_node read (src/lib/automationReadGrant.ts). A row is never edited: it ends with a terminal revokedAt (trigger + CHECKs in app-automation-read-grant-invariants.sql, where the partial unique index also lives). grantedBy / revokedBy carry no FK: sealed history that survives user erasure.

Properties as follows:

  • id:
  • app_id:
  • trigger_kind: SCHEDULE | WEBHOOK (CHECK in app-automation-read-grant-invariants.sql).
  • trigger_id:
  • memory_id:
  • prefix: NULL = the whole memory; otherwise a loc prefix covering itself and its :-boundary descendants.
  • granted_by:
  • created_at:
  • revoked_at:
  • revoked_by:

app_automation_read_grant_events

2883 — append-only record of every automation read grant and revocation: who, which App, trigger, memory and

prefix, and nothing of any node's content. Written in the SAME transaction as the row change and nowhere else. Memory, grant and actor carry no FK on purpose; the App FK cascades so a hard delete still works.

Properties as follows:

  • id:
  • app_id:
  • trigger_kind:
  • trigger_id:
  • memory_id:
  • grant_id:
  • prefix:
  • action: GRANT | REVOKE (CHECK in app-automation-read-grant-invariants.sql).
  • actor_user_id:
  • created_at:

git_mirror_obligations

430 (first slice) — a Git-mirror attempt that did NOT land, recorded so the divergence is no longer silent.

One row per (memory, node, kind, remove_loc, branch): a WRITE row per node/branch, plus one REMOVE row per distinct old loc/branch a move left behind (remove_loc is '' for WRITE). node_id carries NO foreign key on purpose, so a REMOVE row survives the node's hard delete; the memory FK cascades. A row exists only while the last settled attempt failed: success, and ordinary writes to a memory that is not mirrored delete it. The sweep leaves ineligible memories untouched. attempt_seq comes from git_mirror_attempt_seq, taken INSIDE the per-memory checkout lock and settled before it releases, so a stale settle can never overwrite a newer one (src/integrations/github/mirrorObligations.ts). error_class is a fixed, CHECK-constrained set (git-mirror-obligation-invariants.sql); no exception text, URL or token is ever stored. The sweep retries recorded failures only, with capped attempts; no writer-side PENDING or new triggers.

Properties as follows:

  • memory_id:
  • node_id:
  • kind:
  • remove_loc:
  • branch: #3042: resolved attempted branch; empty only for legacy unknown-branch debt.
  • state:
  • error_class:
  • attempts:
  • attempt_seq:
  • last_attempt_at:

automation_versions

Properties as follows:

  • id:
  • app_id:
  • number:
  • entry_source_node_id:
  • compiled_json:
  • version_hash:
  • source_manifest:
  • tier:
  • run_as_user_id:
  • published_by:
  • published_at:
  • approval_hash:
  • approved_by:
  • approved_at:
  • revoked_by:
  • revoked_at:

agent_tasks

1705 (Task Management T1) — one piece of work a team App has assigned, or

wants assigned (cor:agt:050:01). The platform records who holds it, since when, and how it ended; it never reads what the work is.

Shape (CHECK chk_agent_tasks_shape, prisma/agent-task-invariants.sql): exactly one owner and at most one assignee, each a Worker OR a User; the status vocabulary; per-status timestamps; a result only on a finished task. queued (cor:agt:050:03) and waitingOnChildren (cor:agt:050:04) are DERIVED at read time, never stored.

Worker / User references are NO ACTION, not RESTRICT: an App hard delete cascades its workers and its tasks in one statement, and NO ACTION checks at the END of that statement, after both are gone. A worker with tasks is otherwise in use (deleteWorker refuses WORKER_IN_USE).

Properties as follows:

  • id:
  • app_id:
  • task_number

    2553: this task's own segment of its handle: the project number (counted per App) for a top-level row, else the

    number counted within its parent. Assigned once at creation from agent_task_counters, never changed or reissued. 0 is the reserved project AT0 ("no project"). NOT NULL in the database (prisma/agent-task-number-invariants.sql, which also fills it for any writer that leaves it out); optional here only so a writer need not state it.

  • handle

    2553: the full dotted handle (AT3.405.16), composed once at creation from the parent's handle and never

    recomputed: parentage is fixed at creation (a trigger refuses UPDATE of parent_task_id), so it always matches the tree.

  • title: What is asked, in the team's own words. Never read by the platform.
  • description:
  • source: Opaque origin reference (an issue URL, a node URN). Not interpreted.
  • external_id

    3125 S2 (V29, V46; cor:agt:120:02): the claim on an outside item, set once at create. Unique within an App,

    whatever the task's state, through the partial unique index agent_tasks_app_external_id_uniq (raw SQL in agent-task-external-id-invariants.sql: Prisma cannot model a partial unique). Compared exactly as written.

  • parent_task_id: Null for a root task. Always in the same App (cor:agt:050:01).
  • cloned_from_id

    2646 (cor:agt:050:02, What a clone does): the task this one was cloned from, set once at creation and never

    changed. Always in the same App (the clone is made in the source's App). Null for every task not made by a clone.

  • owner_worker_id:
  • owner_user_id:
  • assignee_worker_id: Both null ⇒ queued while pending (cor:agt:050:03).
  • assignee_user_id:
  • requirements: For the matcher (T3): { role?, familyIn?, familyNotIn?, excludeWorkerIds? }.
  • match_pending: #2829: reserve an opt-in match before create commits, so automatic runs cannot race it.
  • match_failed_at: A single-shot failure remains until assignment; cancellation clears it (cor:agt:050:01, ruling 0015).
  • match_failed_reason:
  • properties

    2420 (cor:agt:050:28): this task's OWN optional, platform-opaque JSON object (the team's namespaces: review

    schedule, complexity, a seat's reviewed head). Never inherited, never matcher or authorization input; written by the cor:agt:050:09 set and the task's assignee, validated against the Team Agent's schema:task-properties.

  • status

    'backlog' | 'pending' | 'started' | 'finished' | 'cancelled' (cor:agt:050:02). 'backlog' (#1754): parked — no assignee, not matched, never waited on, no alarms.

  • priority: #2644: 1 is highest; existing tasks retain FIFO within default priority1.
  • blocked: Maintained transactionally with the blocker graph, never caller supplied.
  • released_at:
  • start_by:
  • finish_by

    2648 (cor:agt:050:14): the finish-by deadline. Set, it exempts the task from every stall window; one alarm

    when it passes with the task neither finished nor cancelled.

  • started_at:
  • finished_at:
  • cancelled_at:
  • result_outcome: The result (cor:agt:050:01) — set only on finish.
  • result_summary:
  • result_evidence:
  • result_findings: #2662: immutable ordered findings, set only with the finish result; null is legacy/omitted.
  • finding_dispositions: #2663: latest disposition for each finding, stored beside the immutable result (at most100).
  • unresolved_finding_ids: Derived by the database trigger from resultFindings + findingDispositions; filter before SQL paging.
  • hand_back_reason_code

    2651 (cor:agt:050:29, :01): the latest hand-back — its code (closed set, chk_agent_tasks_hand_back), optional

    text (<= 2,000 characters; never put into an event) and time. A later hand-back replaces all three.

  • hand_back_reason_text:
  • handed_back_at:
  • tags:
  • task_references

    2649 (cor:agt:050:01 References, :09): the task's ordered typed references, a JSON array of

    {kind, target, label} (at most 20, chk_agent_tasks_references). Targets are stored as given and never resolved. Column named task_references: REFERENCES is reserved in SQL.

  • close_session_when_done

    Set by whoever assigns; T6 acts on it (cor:agt:050:10). False unless the assigner asks (R182, #2249): the default only reaches a raw insert, since every create path writes the resolved value.

  • assigned_at: The latest assignment, by hand or by the matcher, in the #1610 actor shape.
  • assigned_by:
  • assigned_by_worker_id:
  • assigned_by_agent_id:
  • created_at:
  • created_by:
  • created_by_worker_id:
  • created_by_agent_id:
  • created_by_run_id

    1756 (cor:agt:050:06): the headless run that created the task, when one did.

    Then createdBy / createdByWorkerId / createdByAgentId are all null. A plain id, not a foreign key: a run is pruned long before its tasks are.

  • updated_at:
  • updated_by:
  • updated_by_worker_id:
  • updated_by_agent_id:

agent_task_blockers

2644: same-App acyclic dependency graph, guarded by task-blocker-invariants.sql.

Properties as follows:

  • task_id:
  • blocker_task_id:
  • created_at:

agent_task_counters

2553: the last number issued under one parent: parentTaskId NULL is the App's project counter. Its own table, so a

task create serializes against other creates under the SAME parent only and never takes the App row exclusively (the App row stays a shared authority anchor). The one-row-per-App project counter is a partial unique index in prisma/agent-task-number-invariants.sql (Prisma cannot model it; NULLs are distinct in the unique below).

Properties as follows:

  • id:
  • app_id:
  • parent_task_id:
  • last_number:

agent_team_events

1705 — one append-only record of something that happened in a team App's

task work (cor:agt:050:11). Never changed or removed: the trigger in prisma/agent-task-invariants.sql refuses every UPDATE except the one-time acknowledgement of an alarm, refuses an INSERT that arrives acknowledged, and refuses a DELETE unless the App itself is gone (the cascade).

payload carries counts, outcomes, reasons and ids only — never message or description text (cor:agt:050:11, Proposed); src/lib/agentTasks/events.ts is its only writer. Actor and subject ids carry no FK on purpose: they are a sealed record of who acted, and an FK action would have to UPDATE the row.

Properties as follows:

  • id:
  • app_id:
  • type: e.g. task.created, task.assigned (cor:agt:050:11).
  • task_id:
  • actor_user_id

    Who acted, in the #1610 shape: the human credential, plus the Worker / Agent bound to the request's session.

  • actor_worker_id:
  • actor_agent_id:
  • actor_run_id: #1756: the headless run that acted, when one did; the other actor columns are then null.
  • actor_app_key_id

    3132 (cor:agt:050:11, :23): the App key that acted, when one did (its one task write is a claim); the other

    actor columns are then null. No FK: like the other actor ids, a sealed record of who acted at the time.

  • subject_worker_id: The worker the event concerns, if any (e.g. the new assignee).
  • subject_user_id

    3132 (rulings:0009): the PERSON the event concerns, when a key or run acted for one it cannot itself resolve

    (the assignee its claim named). Never the actor. No FK, sealed like the actor ids (not rewritten by a merge).

  • severity: null for an ordinary event, 'alarm' for an alarm.
  • chain: Alarms only: the owner chain when raised, nearest first.
  • acknowledged_by_user_id:
  • acknowledged_by_worker_id:
  • acknowledged_at:
  • payload:
  • created_at:
  • episode_start

    1706 — stall alarms only: when the stall episode began (cor:agt:050:13),

    the instant of the move that began the condition, never the evaluator's clock. With taskId and type (the rule) it is the episode's key, and the unique index below is what makes "exactly one alarm per episode" hold across concurrent evaluator passes: a second insert of the same episode is ON CONFLICT DO NOTHING, not a read-then-write. NULL on every other event, and NULLs are distinct, so ordinary events never collide.

agent_team_alarm_schedule

1706 — who an alarm wakes, and when (cor:agt:050:19). One row per owner in

the alarm's chain, by its index there: the nearest owner (index 0) is woken when the alarm is raised, and owner i is due i windows later. The stall evaluator stamps wokenAt once a row is due and its alarm is still unacknowledged; acknowledging stops every later row (cor:agt:050:20).

A side table because the alarm event is append-only. "Woken" here is the platform's record that the owner is now due a wake-up; DELIVERING it is the heartbeat slice's (T5). A person in the chain is recorded as woken the same way, and the timer runs on past them.

Properties as follows:

  • event_id:
  • chain_index:
  • due_at:
  • woken_at:
  • ended_at

    2200 (R196) — when the escalation found that the alarm's OWN episode had ended (the task moved, so the

    condition no longer holds) and closed this row unwoken. Woken or ended, never both (chk_agent_team_alarm_schedule_shape); the alarm event, its chain and every woken_at stay as written.

dark_worker_episodes

2755 — one dark-worker episode (a worker that went OVERDUE or left a due wake unacknowledged past the App's

window). The alarm event stream is append-only, so an episode's end lives here. At most one OPEN row per worker (partial unique index in prisma/dark-alarm-invariants.sql): the worker's single open episode across both reasons. reason is the trigger that opened it. The episode ends when BOTH conditions have cleared.

Properties as follows:

  • id:
  • app_id:
  • worker_id:
  • event_id: The task-less alarm raised with the episode (agent_team_events, type alarm.dark-worker).
  • reason: overdue | wake-unacked.
  • opened_at:
  • ended_at:
  • notice_posted_at: When the platform's one team-channel post for this episode was written; NULL until then (retried each pass while the episode is open).

coordinator_cadence_episodes

2763 — one coordinator-cadence episode: a coordinator that stopped assigning while a lane worker was free (cor:agt:050:31,

Proposed). It de-duplicates the task-less alarm raised with it (agent_team_events, type alarm.coordinator-cadence, task_id NULL, which agent_team_events_episode_uniq cannot dedupe). At most one OPEN row per coordinator (partial unique index in prisma/coordinator-cadence-invariants.sql); the episode ends only at the coordinator's next counted assignment.

Properties as follows:

  • id:
  • app_id:
  • worker_id:
  • event_id:
  • opened_at:
  • ended_at:

coordinator_cadence_clocks

2763 — when the evaluator first saw each coordinator, so a coordinator that existed before the deploy (or never assigned)

is not late at the first pass. Inserted once, ON CONFLICT DO NOTHING; never updated.

Properties as follows:

  • worker_id:
  • app_id:
  • observed_at:

post_limit_episodes

2014 — one post-limit episode: the first refusal of a worker's team-chat post by the rate limit in an hour. It only

de-duplicates the alarm raised with it (agent_team_events, type alarm.post-limit); the alarm itself stays open until acknowledged. At most one OPEN row per worker (partial unique index in prisma/post-limit-invariants.sql); an open episode older than an hour is closed (endedAt = openedAt + 1 hour) by the next refusal, which then opens a new one.

Properties as follows:

  • id:
  • app_id:
  • worker_id:
  • event_id:
  • opened_at:
  • ended_at:

worker_availability

1706 — one worker's availability for work (cor:agt:060:02). At most one

row per worker, and a worker with none is available (Proposed). The row is kept when the worker becomes available again, for history. An until that has passed reads as available at once, and the matcher's sweep rewrites the row to available, set by lapse, with one event (#1766).

setBy names the setter class of cor:agt:060:08: worker (itself, only to unavailable), holder, app-manager, reports-to (#1759: the worker it reports to, only clearing a stall-rule mark, 060:11), stall-rule (060:07) or host (T6); or lapse (#1766), the platform recording a passed until. The actor ids follow the #1610 shape. Shape: chk_worker_availability_shape (prisma/agent-task-stall-invariants.sql).

Properties as follows:

  • worker_id:
  • state: 'available' | 'unavailable'.
  • reason: Unavailable only: 'stalled' | 'out-of-tokens' | 'host-down' | 'other'.
  • until:
  • set_at:
  • set_by:
  • set_by_user_id:
  • set_by_worker_id:
  • set_by_agent_id:
  • set_by_host_id

    1709 — the host whose key set this record (setBy = host only), so a

    host clears only its own marks (cor:agt:060:08).

  • clears_on_activity_after

    2162 (cor:agt:050:27) — a resetting mark only: the instant the host reported the old agent stopped. The

    worker's first activity AFTER it ends the mark (the relaunched agent's first call); null while the old agent may still be running, when no activity ends it.

  • context_reset_id

    2162 (cor:agt:050:27) — a resetting mark only, and always on one: the reset that claimed it. A reset moves or

    releases only its own mark, so an older reset still open after its lease lapsed never touches a newer one's. No FK: both rows go with their worker (cascade), and the shape CHECK pairs this with the reason.

model_groups

2831 S1 (cor:agt:060:12) — a model group: an opaque name over a list of model

patterns (globs), declared by the team Agent (agentId) or by an App (appId, an override of the Agent's group of that name, or an App-only group). Exactly one owner (chk_model_group_owner). Resolved LIVE at match time, App's row else the Agent's (src/lib/agentTasks/modelGroups.ts); never copied at install. The platform gives name and patterns no meaning, and a group is never an authorization input. name and every pattern are stored lowercase.

Properties as follows:

  • id:
  • name:
  • agent_id:
  • app_id:
  • patterns:
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:

model_family_availability

1706 — one model family's availability for work in one App

(cor:agt:060:03): at most one row per App and family; with none, the family is available. Set only by whoever manages the App (cor:agt:060:09).

Properties as follows:

  • app_id:
  • family: The model family, e.g. claude, codex, glm (cor:agt:060:04).
  • state:
  • reason:
  • until:
  • set_at:
  • set_by_user_id:
  • set_by_worker_id:
  • set_by_agent_id:

agent_task_stall_schedule

1706 — an App's stall windows, in minutes (cor:agt:050:14–:17 "What Can

Change"). A NULL column, or no row, means the platform default (src/lib/agentTasks/stall.ts STALL_WINDOW_DEFAULTS). Tunables, not contract; set by whoever manages the App.

Properties as follows:

  • app_id:
  • not_started_minutes:
  • no_progress_minutes:
  • owner_reaction_minutes:
  • assignment_minutes:
  • host_lapse_check_ins

    1763 (cor:agt:070:01) — how many of a host's own check-in intervals may

    pass without a refresh before its registration in this App lapses: 2 to 10 (chk_agent_task_stall_schedule_range); null is the default, 3.

  • session_end_grace_minutes

    1709 (cor:agt:050:10) — how many minutes a worker asked to end its

    session on its task's finish or cancellation has before the platform ends it through its host: 1 to 1440; null is the default, 10.

  • host_report_timeout_minutes

    1881 (cor:agt:070:02) — how many minutes a host has to report an

    operation it collected before the platform fails it: 5 to 1440; null is the default, 60.

  • updated_at:
  • updated_by:

host_registrations

1707 — a host's statement of which team App it serves and which workers it

can launch, each with the model family it would run as (cor:agt:070:01). Identified within its App by hostId (Proposed); label is for display.

The host's identity comes from its key, never from a request: the public registerHost mutation (#1709) takes the host id from the calling key's host:operate scope row (cor:agt:070:04). The writer is src/lib/agentTasks/hosts.ts.

A registration not refreshed within LAPSE_POLLS poll intervals has lapsed (plan default 3, cor:agt:070:01 open question): its workers stop counting as launchable through it, and the sweep writes host.lost once, stamping lostAt. A refresh clears lostAt.

Properties as follows:

  • id:
  • app_id:
  • host_id:
  • label:
  • poll_interval_seconds:
  • registered_at:
  • refreshed_at:
  • lost_at:
  • capabilities

    2162 (cor:agt:070:01, Proposed) — the capability-gated operation types this host declared it performs. A host

    is never issued such a type unless its live registration lists it; today that is only worker.reset-context.

host_registration_workers

1707 — one worker a registered host can launch, and the model family it

would run as (cor:agt:070:01). A worker may be launchable through several hosts (Proposed).

Properties as follows:

  • registration_id:
  • worker_id:
  • family:
  • worktrees

    1709 — the worker's existing worktrees on this host, as the host names

    them (tokens the host resolves from its own configuration, never paths the platform invents). A worker is started only in one of these (cor:agt:070:06, :08); empty means it has none here.

host_operations

1709 (Task Management T6) — one typed operation the platform issued to one

host of a team App (cor:agt:070:02). type is one of the closed set of cor:agt:070:03 and args its typed arguments, validated at issue (src/lib/hostOperations/types.ts); there is no free-form type.

Status (070:02, collected Proposed by #1709): issued → collected (the host took it) → succeeded | failed (the host reported; a failure carries a reason). Each outcome also writes host.operation.succeeded / .failed. Only the host it names collects or reports it (070:04). The issuer is a person, a worker (through its session) or the platform (issuedBy). Shape: prisma/host-operation-invariants.sql.

Properties as follows:

  • id:
  • app_id:
  • host_id:
  • type:
  • args:
  • worker_id: The worker the operation is for; every type names one.
  • status:
  • issued_by: user | worker | platform.
  • issued_by_user_id:
  • issued_by_worker_id:
  • issued_by_agent_id:
  • issued_at:
  • collected_at:
  • finished_at:
  • result: The typed result a success reports (e.g. the created worktree).
  • failure_reason: Why it failed, as the host said it; failures only.
  • hold_user_id

    1709 slice 2 (#1883 review, Diego P2-1) — worker.start only: the hold

    that authorized the start, as (holder, held-at) when it was issued. A grant is minted, and a bind made, only while the worker's hold is still exactly this one: a release and re-hold changes heldAt, a move or an account merge changes the holder (Holger via Vera #10775).

  • hold_at:

resume_claims

1956 (cor:agt:020:03; Holger via Vera #11904, the window #12291) — a resume

claim: written by a worker session's own driver before a deliberate context reset (a shed keeps the session open; a rotation ends it with its handoff), so the fresh context can recover its worker with one call and no arguments, with no binding file. Single use, consumed by a guarded update; it lives RESUME_CLAIM_TTL_MS (60 s) from the write. Redeemable only by its holder, judged by the caller's token, never by anything the caller presents: the claim carries no secret and its id is never shown, so a non-holder has nothing to present and learns nothing. Same mechanics family as LaunchGrant (#1883), but it authorizes nothing the holder could not already do by naming the worker.

Properties as follows:

  • id:
  • app_id:
  • session_id:
  • worker_id:
  • holder_user_id:
  • issued_at:
  • expires_at:
  • consumed_at:
  • resumed_session_id

    The session the redemption bound: the claimed one when it was still open, or the new session started for its worker when it had ended.

  • revoked_at: Set when a newer claim for the same session replaced this one unused.

launch_grants

1709 (T6 slice 2; Holger's ruling A, Vera #10761) — a single-use launch

grant: the proof a host passes to the agent it starts, which the agent redeems at startSession for an ordinary worker session. Minted when the host COLLECTS a worker.start (so no secret is stored in the operation), bound to (worker, host, task, holder), short-lived, stored only as a hash. Redeemable only by the holder, judged by the caller's token, never by the grant; consumed atomically. A re-collection revokes the unconsumed grant before minting a new one. Never a credential: it authorizes nothing the holder's own token does not.

Properties as follows:

  • id:
  • app_id:
  • operation_id:
  • worker_id:
  • host_id:
  • task_id:
  • holder_user_id:
  • token_hash:
  • issued_at:
  • expires_at:
  • consumed_at:
  • session_id:
  • revoked_at:

context_resets

2162 (cor:agt:050:27) — one context reset of a worker, requested when a task it had started finished or was

cancelled. At most one per task (taskId unique: a task ends once). The phase only moves forward: requested → claimed → checkpointed → stop-granted → agent-stopped → relaunched → done, or to refused / failed with a closed reason. epoch moves at claim and at every cancellation, so a host call naming an older epoch is refused STALE_EPOCH. The host operation keeps its own 070:02 status; this row is the reset's protocol state. Never reads or writes the task's outcome.

Properties as follows:

  • id:
  • app_id:
  • worker_id:
  • session_id: The worker's session open when the task ended: the fence the claim re-checks.
  • task_id:
  • host_id: The host the reset was issued to; null when no capable live host registered the worker (HOST_UNSUPPORTED).
  • host_operation_id:
  • phase:
  • reason: Refused or failed only: a word from the closed set (src/lib/contextReset/types.ts).
  • epoch:
  • requested_at:
  • claimed_at:
  • claim_process: The agent process the host observed at claim: {pid, startTime}.
  • recovery_ref: {checkpointNodeId, sessionId, taskId}, registered before any process control.
  • recovery_registered_at:
  • stop_granted_at:
  • stop_lease_ms:
  • agent_stopped_at:
  • relaunched_at:
  • relaunch_process:
  • release_pending_at: When a cancellation found a stop lease outstanding: the mark lifts no earlier than this.
  • ended_at:

task_session_end_requests

1709 (cor:agt:050:10) — a task's request that its assignee end its worker

session: written when a task with closeSessionWhenDone finishes or is cancelled while its worker assignee has an open session. One per task.

The worker is asked first; at dueAt (the App's grace, default 10 minutes) the sweep resolves it: ended (the session ended, by the worker or otherwise), end-issued (still open: the platform issued worker.end for that exact session to a live host registering the worker; operationId), or no-live-host (still open, no live host: nothing more happens). A replacement session is never touched: only sessionId is ever ended.

Properties as follows:

  • id:
  • app_id:
  • task_id:
  • worker_id:
  • session_id:
  • event_id: The task.session-end-requested event this request wrote.
  • requested_by_worker_id: The worker that finished or cancelled the task, when a worker did.
  • requested_at:
  • due_at:
  • resolved_at:
  • resolution: ended | end-issued | no-live-host; null while open.
  • operation_id:

host_key_uses

1709 — one use of a host key (cor:agt:070:07: every use is recorded):

which key, for which App and host, what it did, and when. operationId names the operation a report was about; count how many operations a collection returned or workers a registration listed.

Properties as follows:

  • id:
  • app_key_id:
  • app_id:
  • host_id:
  • action

    register | collect | report | availability | read (#1881: the App's host registrations or host-operations listing, read with the key;

    2931: its host's tickers, count the rows returned) |

    session (#1969: a refused session write; always carries a refusedCode).

  • operation_id:
  • count:
  • refused_code

    1881 (cor:agt:070:07, Holger #10849): the refusal's code when the call

    was refused, written apart from the refused call so its rollback keeps it.

  • used_at:

manual_automation_pins

1719: mutable manual-trigger consent kept apart from the immutable run snapshot.

Properties as follows:

  • run_id:
  • pin:
  • adopted_at:
  • adopted_by:

tickers

1747 (Tickers S1) — a named wake schedule owned by one team App

(cor:agt:080:01). Ticks are COMPUTED from anchorAt + k x cadenceSeconds, never stored (cor:agt:080:06). Nothing reads a ticker until S2.

The NAME is unique among live tickers, ignoring case, and reusable after a delete (partial index tickers_app_name_live_uniq); the SLUG is permanent: unique within the App forever, deleted rows included (tickers_app_slug_uniq), so a re-created engineering gets engineering-2 (#8083). Owner is exactly one of user / worker, taken from currentActor(), never an argument (CHECK chk_tickers_shape, prisma/ticker-invariants.sql).

Properties as follows:

  • id:
  • app_id:
  • name:
  • slug:
  • tick_code: Permanent action-register code, snapped from the template name for generated tickers.
  • cadence_seconds:
  • anchor_at:
  • quiet_hours: { timezone, windows: [{ days: [1..7], from: "22:00", to: "07:00" }] }.
  • channel_ids: Null = every channel the subscriber watches. Not a grant (cor:agt:080:01).
  • relevance: 'ALL' | 'MENTIONS'.
  • reasons

    2068 (cor:agt:080:01, :10, R49): why the ticker fires, a closed set: 'read-team-channel' (relevant unread, as before) and

    'every-tick' (unconditional), and 'live-check' (#2138: the worker has not checked its team channel within the ticker's cadence, whatever is unread; never for a worker not expected to check). Empty = never fires; any-of when several (Decided, R54).

  • enabled:
  • owner_user_id:
  • owner_worker_id:
  • source_template_id

    2024 (S8): set only on a ticker the platform generated at cast from an Agent ticker template. The template

    is a plain reference (no FK, so removing a template never cascades into runtime state) and the revision is the one the ticker was made from; generatedForWorkerId is the worker it was made for. A partial unique (generatedForWorkerId, sourceTemplateId) over live rows makes a retried cast unable to mint a second live instance.

  • source_template_revision:
  • generated_for_worker_id:
  • edited_at

    2429 (cor:dmo:050:11): set by every accepted updateTicker on a GENERATED ticker, whatever the fields and even when

    the values end up unchanged (it fails toward blocking). An edited generated ticker is no longer the cast's own bookkeeping, so it counts as a reference and blocks the miscast repair. Soft-deletes are not edits.

  • created_at:
  • created_by:
  • created_by_worker_id:
  • created_by_agent_id:
  • updated_at:
  • updated_by:
  • updated_by_worker_id:
  • updated_by_agent_id:
  • deleted_at:
  • deleted_by:
  • deleted_by_worker_id:
  • deleted_by_agent_id:

agent_ticker_templates

2024 (S8, cor:agt:080:33) — one ticker an Agent declares. Casting a worker from the Agent into an App creates

the worker's tickers from these (a SNAPSHOT: a later edit or removal reaches only future casts, R96 A) and subscribes it. Identity is id, never the name or a position; revision counts edits so a stale writer is refused (expectedRevision); shapeVersion lets a future shape be decoded explicitly (an unknown one is refused). Soft-deleted rows stay, because generated tickers keep their provenance. Live names are unique per Agent ignoring case; the CHECKs mirror the ticker's (prisma/agent-ticker-template-invariants.sql).

Properties as follows:

  • id:
  • agent_id:
  • revision:
  • shape_version:
  • name:
  • cadence_seconds: Requested cadence; the cast clamps it up to the App's floor (R92).
  • quiet_hours:
  • relevance: 'ALL' | 'MENTIONS'.
  • reasons: Closed set, non-empty: 'read-team-channel' | 'every-tick' | 'live-check' (a template with none would never fire).
  • created_at:
  • created_by:
  • updated_at:
  • updated_by:
  • deleted_at:
  • deleted_by:

ticker_subscriptions

1747 — a worker's subscription to one ticker (cor:agt:080:02). Workers of the

ticker's App only, never Agents. One LIVE row per (ticker, worker) (partial index ticker_subscriptions_live_uniq). History is kept, never hard-deleted. endedReason is UNSUBSCRIBED | WORKER_RETIRED | TICKER_DELETED, never dormancy (#8099). viaGrantId + viaGrantPersonId record a grant use (N2).

Properties as follows:

  • id:
  • ticker_id:
  • worker_id:
  • created_at:
  • created_by:
  • created_by_worker_id:
  • created_by_agent_id:
  • via_grant_id:
  • via_grant_person_id:
  • ended_at:
  • ended_by:
  • ended_by_worker_id:
  • ended_by_agent_id:
  • ended_via_grant_id:
  • ended_via_grant_person_id:
  • ended_reason:

worker_wake_settings

1747 — one worker's wake settings (cor:agt:080:03), created lazily.

mentions is IMMEDIATE | OFF (no ON_TICK, #8090). pausedUntil belongs to the worker, not a session (#8077).

Properties as follows:

  • worker_id:
  • mentions:
  • paused_until:
  • isolated_until

    S7 (#2023, R85) — ISOLATION is its own state, never pausedUntil: written only by isolateWorker / clearWorkerIsolation, always by a human acting as themselves.

  • isolated_at:
  • isolated_by_user_id:
  • exempt_ended_at

    2755 — when an ACTIVE pause or isolation was ended on purpose (clearPause, clearWorkerIsolation), which erases

    the only timestamp that said when the exemption ended. Natural expiry needs none (its own end stays stored).

  • updated_at:
  • updated_by:
  • updated_by_worker_id:
  • updated_by_agent_id:

worker_delivery_channels

1747 — the delivery record, part 1 (cor:agt:080:04): the newest seq a wake

for a channel was acknowledged for. Created here, WRITTEN ONLY by S2's acknowledgeWakes. It only rises.

Properties as follows:

  • worker_id:
  • channel_id:
  • channel_incarnation:
  • delivered_through_seq:
  • delivered_at:
  • acked_by_user_id

    Who acknowledged the newest wake (cor:agt:080:16): a person, a worker's session behind them, or a bare App key (S3).

  • acked_by_worker_id:
  • acked_by_app_key_id:

worker_wake_acks

2072 (Holger R53, cor:agt:080:04/:13/:15) — the receipt of an acknowledged wake, per (worker, wake key). A wake

carries no message text, so its acknowledgement moves no message mark; this row is what it records instead: the floor's clock (ackedAt) and the budget's once-per-wake test. A row is (re)written only by an acknowledgement of a proof issued AFTER both the receipt and its accepted-issue watermark, so a repeat or an older proof's replay changes nothing while the same wake offered again after the floor counts again.

Properties as follows:

  • worker_id:
  • wake_key:
  • acked_at:
  • issued_at

    3022: issue time that spent/covered this key; absorbed keys inherit the descendant's issue time.

    NULL is an old writer's receipt: replay comparison falls back to ackedAt.

  • acked_by_user_id:
  • acked_by_worker_id:
  • acked_by_app_key_id:

worker_delivery_ticks

1747 — the delivery record, part 2: the last tick acknowledged per ticker.

WRITTEN ONLY by S2.

Properties as follows:

  • worker_id:
  • ticker_id:
  • last_acked_tick:
  • acked_at:
  • acked_by_user_id:
  • acked_by_worker_id:
  • acked_by_app_key_id:

worker_delivery_task_events

1708 (Task Management T5) — the delivery record, part 3: one row per

(worker, task event, alarm chain position). deliveredAt is set ONLY by acknowledgeWakes (a wake proof naming the event), and is the receipt that the nudge for this event reached this worker. It is never an alarm acknowledgement (cor:agt:050:20): that stays acknowledgeAlarm's. undeliverableAt is set by the stall-evaluator tick when the subject is dormant (cor:agt:080:11); a later delivery still records deliveredAt. chainIndex is 0 for an ordinary event and the woken position for an alarm.

Properties as follows:

  • worker_id:
  • event_id:
  • chain_index:
  • delivered_at:
  • acked_by_user_id:
  • acked_by_worker_id:
  • acked_by_app_key_id:
  • undeliverable_at:
  • undeliverable_reason: 'dormant' — the only reason this slice records.

app_wake_days

1748 — wakes acknowledged per App per UTC day (cor:agt:080:15). wakes is

the budget counter (exempt wakes are not counted); noticePostedAt is the once-a-day "budget spent" notice claim. Written only by acknowledgeWakes and the notice claim.

Properties as follows:

  • app_id:
  • day:
  • wakes:
  • notice_posted_at:

app_wake_reservations

1748 cycle 1 — an outstanding budget reservation: dueWakes issued a

non-exempt wake proof for this worker and has not yet seen it acknowledged. Counted against the day's budget for as long as the proof could still be acknowledged (15 minutes), so concurrent readers cannot hand out more than the budget (cor:agt:080:15). One row per worker; refreshed by a re-read, removed by the acknowledgement.

Properties as follows:

  • worker_id:
  • app_id:
  • reserved_at:
  • wake_key

    Which wake it was reserved for (the proof's channels, seqs and ticks, hashed): an acknowledgement spends only the reservation of the wake it delivers, so an old proof replayed cannot cancel a newer wake's allowance.

  • wake: The wake itself, so an outstanding one is handed out again, exactly, until it is consumed or lapses.
  • absorbed_keys

    2069: the wake keys this reservation absorbed (a tick or task that fell due after them). An earlier proof whose key

    is listed shares this reservation's allowance and is not charged again; any other proof is unrelated to it.

team_stop_signals

2022 (S6, cor:agt:090:01) — a stop signal: team state that stops work for the workers it covers until it ends.

Level pause-dispatch | pause | halt; scope worker | team | host. A worker or team signal names its target worker (a team by its head); a host signal names its host registration. Who set it is a person (setByUserId) or a host key (setByAppKeyId), never both. It is live while endedAt is null and until (when given) has not passed: an expiry is in effect at until even before the sweep records it. The level, scope, target, setter and set time never change; the end is recorded once (prisma/stop-signal-invariants.sql). No text.

Properties as follows:

  • id:
  • app_id:
  • level:
  • scope:
  • target_worker_id:
  • target_host_registration_id:
  • set_at:
  • until:
  • set_by_user_id:
  • set_by_app_key_id:
  • ended_at:
  • end_kind: lifted | expired.
  • ended_by_user_id:
  • ended_by_app_key_id:

stop_consumer_declarations

2169 (S6b, R95) — one serving lane's declaration that its consumer takes stop notices: a dueWakes call that

passes accepts: [STOP] upserts the row of the lane it serves (a host registration id for a host key, unhosted for a person who manages the App or a non-host key). A declaration is FRESH for STOP_CONSUMER_FRESH_SECONDS; setting a stop signal is refused while any worker it would cover has no fresh lane. lane is deliberately not a foreign key: it is either a registration id or the literal unhosted, and a stale row for a deleted registration is simply never read.

Properties as follows:

  • app_id:
  • lane:
  • declared_at:

team_stop_coverage

2022 (R95) — when a stop signal covered a worker: the HISTORY that stall clocks and notices read. Enforcement never

reads it; it works coverage out live (cor:agt:090:02). Kept by reconcileStopCoverage under the App's stop fence: one open interval per (signal, worker) (partial unique index, prisma/stop-signal-invariants.sql). An interval ends at the earliest of leftAt, its signal's end and its signal's until.

Properties as follows:

  • id:
  • app_id:
  • signal_id:
  • worker_id:
  • entered_at:
  • left_at:

agent_task_stop_holds

2022 (R68, Vera's receipt §5) — a time when stop signals were what kept a queued task from being assigned: every

worker that would otherwise match it was covered, or its creator was under a pause or halt (R71). The couldn't-be-assigned clock (cor:agt:050:17) doesn't count it. Opened and closed by the matcher's pass; one open hold per task (partial unique index).

Properties as follows:

  • id:
  • app_id:
  • task_id:
  • started_at:
  • ended_at:

app_grants

1747 — a narrow, named App grant held by a WORKER (cor:agt:080:24). One

live row per (app, grantee, name) (partial index app_grants_live_uniq). name is a closed list: ticker.subscribe-workers. Given and revoked only by whoever manages the App.

Properties as follows:

  • id:
  • app_id:
  • grantee_worker_id:
  • name:
  • granted_at:
  • granted_by:
  • revoked_at:
  • revoked_by:

app_key_scopes

A scope an App key holds (cor:aut:010:03, #1749). A closed list; today only attention:deliver. At most one LIVE row per key and scope (a partial unique index, prisma/app-key-scope-invariants.sql). Granted and revoked only by whoever manages the App; read from the database on every call it gates, never cached in the auth context.

Properties as follows:

  • id:
  • app_key_id:
  • scope:
  • granted_by_user_id:
  • granted_at:
  • revoked_by_user_id:
  • revoked_at:
  • host_id

    1709 — the one host a host:operate scope is bound to (cor:agt:070:04):

    required for that scope, absent for every other (chk_app_key_scopes_shape).

app_key_wake_reads

One row per App-key dueWakes call: which key read, how many workers it was shown, when (#1749, cor:agt:080:23).

Properties as follows:

  • id:
  • app_key_id:
  • app_id:
  • worker_count:
  • read_at:

user_deletion_audits

1647 (cor:aut:020:03): one row per erasure a platform admin performs on ANOTHER user's account. Written in the

deletion's own SERIALIZABLE transaction, so the audit and the erasure commit or roll back together. User ids are plain columns, deliberately NOT foreign keys: the audit must outlive any cascade. Immutable (trigger in post-push.sql + the migration) and exposed on no read surface.

Properties as follows:

  • id:
  • actor_user_id:
  • target_user_id:
  • reason:
  • completed_at:

user_deletion_notices

1647: the outbox for the deleted user's notice. Written in the deletion's transaction with the recipient address

encrypted (tokenCrypto); a post-commit worker sends it and clears the ciphertext at a terminal state. The notice text never carries the audit reason.

Properties as follows:

  • audit_id:
  • status:
  • recipient_ciphertext:
  • attempts:
  • lease_until: Exclusive send lease: while leaseUntil is in the future only the holder of claimToken is sending.
  • claim_token:
  • created_at:
  • updated_at:

worker_reference_fences

1162: internal MVCC coordination, not authored history or a Worker FK.

Writers and miscast deletion update this version in their own transaction. Retained after deletion to fence older snapshots; no public API. The key is an immutable Worker id.

Properties as follows:

  • subject_id:
  • version:

served_prompts

2047 (S10, cor:agt:040:03): what a bind, a chatbot chat or a headless run was given. IMMUTABLE platform data, not

memory content: it names the compiled revision served, the pointer level that chose it, that revision's own provenance (copied from the revision at serve time, so a recompile never rewrites it, R38) and the values the platform variables were filled with. No composed text, no derived blocks (run progress holds those), no export.

Identity of a revision is (compiledNodeId, servedRevSeq): Node.revSeq, never contentRevSeq. compiledNodeId is deliberately not a foreign key: the record outlives a deliberately deleted node and shows it as pruned.

Owner (exactly one of session / chat node / run), the owner-consistency foreign keys, immutability and the owner-absence delete gate are database facts Prisma cannot model: prisma/served-prompt-invariants.sql.

Properties as follows:

  • id:
  • kind:
  • session_id:
  • chat_id:
  • run_id:
  • ordinal: 1 for a bind or a run; a chat records again when its served revision or filled variables change (R37, #3096), counting up.
  • app_id: Null only for a chat held in a memory no App owns (chk_served_prompts_app, prisma/served-prompt-app-invariants.sql).
  • agent_id:
  • worker_id:
  • pointer_level:
  • compiled_node_id:
  • served_rev_seq:
  • provenance_rev_seq

    The compile revision that owns the provenance: the greatest compile revSeq at or below the served one (a metadata-only revision above a compile advances revSeq but not the provenance).

  • compiled_content_hash:
  • provenance: [{nodeId, revSeq, hash}], read through its own cursor field, never in one response.
  • variables:
  • served_at:

agent_clone_audits

2245 (R170.6): one append-only record per Agent clone. Written in the clone's own transaction, so the audit and

the copy commit or roll back together. Ids are plain columns, deliberately NOT foreign keys: the record must outlive the Agents, orgs and users it names. Exactly one of the two targets is set (CHECK in post-push.sql); S1 only writes targetOrgId. Immutable (trigger) and exposed on no read surface.

Properties as follows:

  • id:
  • actor_user_id:
  • source_agent_id:
  • new_agent_id:
  • target_org_id:
  • target_user_id:
  • node_count:
  • edge_count:
  • skipped_edge_count:
  • import_count:
  • link_count:
  • created_at:

node_edge_removals

2517, cor:dmo:010:04 (Proposed) — a separate audit entry, written on each SOURCE node, when a hard

delete cascades an edge that node held to the deleted target. Deliberately NOT a NodeRevision (a node's revisions stay snapshots of its own fields). The source is a real FK (the trace dies with the source); the target is NOT one, since the target row is gone by the time anyone reads this.

Properties as follows:

  • id:
  • source_id:
  • memory_id: The source's memory when the edge was removed (a node can later be moved).
  • edge_id:
  • edge_loc:
  • edge_name:
  • target_id:
  • target_memory_id:
  • target_loc:
  • reason: Why the edge went: today only TARGET_HARD_DELETED.
  • removed_by: Same value Node.deletedBy would carry (user, app or client id), null when unattributed.
  • created_at:

1667, cor:dmo:060:15 — append-only record of every successful per-asset

public-link switch call: who, when, to what. Written in the SAME transaction as the flag. Deliberately NO foreign keys: the record must outlive the asset row (the janitor hard-deletes assets) and the actor.

Properties as follows:

  • id:
  • asset_id:
  • memory_id:
  • actor_user_id:
  • enabled:
  • previously_enabled:
  • created_at:

include_references

Properties as follows:

  • id:
  • includer_id:
  • ordinal:
  • kind:
  • reference:
  • target_memory_id:
  • target_loc:
  • pinned_rev_no:
  • requires_approved:
  • requires_signed:
  • metadata_generation:

include_source_coverage

Properties as follows:

  • id:
  • includer_id:
  • source_revision:
  • source_memory_id:
  • source_loc:
  • source_content_fingerprint:
  • source_encrypted:
  • parser_version:
  • metadata_generation:
  • reference_count:
  • state:

include_retention_generation

Properties as follows:

  • id:
  • schema_version:
  • parser_version:
  • metadata_generation:
  • state:
  • source_high_water_id:
  • replay_cursor:
  • binding_generation:
  • verified_binding_generation:
  • source_count:
  • covered_count:
  • blocked_count:

rate_limit_policies

1793: server-owned policy; defaults seed once, mode deploys LOG_ONLY.

Properties as follows:

  • field_class:
  • principal_limit:
  • key_limit:
  • ip_limit:
  • window_seconds:
  • retention_seconds:
  • enforcement_mode:
  • version:
  • updated_at:

rate_limit_buckets

1793: HMAC subjects only. Window-independent advisory locks protect absent rows too.

Properties as follows:

  • id:
  • field_class:
  • dimension:
  • subject:
  • window_start:
  • used:
  • expires_at:

rate_limit_manifests

1793: no secrets, only key IDs and fingerprints. Operators fence overlap/drain transitions.

Properties as follows:

  • id:
  • key_ids:
  • fingerprints:
  • overlap_started_at:
  • version:

rate_limit_policy_audits

1793: platform-admin-only configuration audit; contains no subject/counter/secret.

Properties as follows:

  • id:
  • field_class:
  • actor_id:
  • before:
  • after:
  • change_reference:
  • created_at:

_AppToUser

Pair relationship table between apps and users

Properties as follows:

  • A:
  • B: