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:handleUnique username, e.g. "holger"; displayed as
@holgerin UI and node frontmatterauthorfield, 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 viagenerateUniqueHandle; the DB-generated random default is a backstop for handle-omitting inserts (test fixtures) so those need no churn. Case-insensitive uniqueness is theusers_handle_lower_uniqfunctional index (post-push.sql); the@uniquehere is the plain case-sensitive one.policyUser-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_idGoogle account id — the OIDC
subclaim (#581). A string of digits, but stored as text: Google documents it as an opaque string and it can exceed 2^53.apple_idApple account id — the Sign-in-with-Apple
subclaim (#584). An opaque team-scoped string (e.g. "001234.abcd1234ef….0102").identity_provider:external_id: App-scoped external user id. Composite-unique withexternalAppId.external_app_idThe App that minted this externalId. Forms a (App, externalId) idempotency key for chatbot user provisioning.
linked_atWhen 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_referralsMaximum 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).configWidget-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.configThe 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:urnThe 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_marketplaceOpt-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
isVisiblelisting flag with the auto-personal org — every org now lists.)github_installation_idGitHub 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_encryptedAES-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:policyOrg-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:nameThe canonical root name, stored lowercase.
@uniqueis 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 thefindUniqueavailability probe. Spans ALL statuses (no status filter), so areleasedtombstone 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_inviteWhether 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_idThe user TENANT owner of a user-owned Memory (rooted on the bare
<handle>— #697 v2, no@sigil). DISTINCT fromuserId(the personal/private strict-owner). The exactly-one-oforganizationId/ownerUserIdXOR is ENFORCED —chk_memory_owner_xorin 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_idThe App this memory belongs to. Required when
classisapp; optional forknowledge/group/personal/private(set when app-scoped, NULL when free-standing); NULL forsystem. Enforced by chk_memory_class_app_id (#653 allowed knowledge + group to attach to an App).user_idOwning 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_idAgent 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_id723 — the IDENTITY of an App's
sharedapp-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-addressablecreateMemoryInAppapp-class memories), so@@unique([appId, sharedMemoryOfAgentId])is the find-or-create key forfindOrCreateAppClassMemory— 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 throughsplitNodeUrn, 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'ANDapp_id IS NOT NULL).install_of_agent_id2044 (S7) — the IDENTITY of an App's INSTALL MEMORY: the Agent this¶
class='system'row customises forappId(cor:agt:040:06). Set ONLY there; NULL on every other row, including an Agent's own system memory (which isapp_id IS NULLand is reached throughAgent.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_memoryR94 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.
urnGlobally 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.dataFree-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.schema725 — 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). Nodeproperties/objectTypeare validated against it in the enforcement phase (a later PR) — free-form until then.corpus_draft1591 — 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_at1591 — 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_encryptedAES-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_atExpiry of the stored token; server warns via MemoryLogEntry before expiration.
read_branch: Branch to clone/pull from (default: repo default branch).read_branch_corrected1566: 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").visibility035-visibility-enum-cleanup: nullable, no default. Set only for
knowledge(PUBLIC/ORGANIZATION) andgroup(GROUP); NULL for system/app/personal/private (enforced by chk_memory_visibility_class).listed_on_marketplaceOpt-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_encryptedWhether the memory's contents (including asset bytes) are encrypted at rest using AES-256-GCM under HADRON_ENCRYPTION_KEY.
classPer-class governance — see MemoryClass enum doc for the four classes and their addressing rules.
anonymous_expires_atWhen 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_countNumber of live unresolved PendingEdge records whose live source is in this memory (a derived projection, denormalized for dashboard display).
accepts_uploadsWhether this memory accepts asset uploads. system-class memories typically opt out.
vector_index_enabledOpt-in: when true, this memory's nodes are vector-indexed. DB default is
false; the class-derived default is applied at createMemory — aknowledge-class, non-encrypted memory is created withtrue, all other classes and any encrypted memory stayfalse(FR-001). Flippable per memory.embedding_sourceWhat the vector index is built from. Memory property, NOT a query parameter (FR-002). Only meaningful when vectorIndexEnabled.
chunk_tokensPer-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_count621 — 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_saltSpec 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_verifierenc: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_atTimestamp 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_atOnline 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_reasonSpec 021 sentinel for data-defect rows during the FR-032 migration. TODO(spec-021-cleanup): drop alongside urnNormalizedAt.
legacy_urn697 stored alias map: the pre-v2 (v1) URN this row was migrated FROM.¶
Null until the online migration flips
urnto the flat v2 form; then a legacy input (wikilink, export, external link) resolves to this row by matchinglegacyUrn. 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_idThe Memory this asset belongs to; NULL while the asset is staged (uploaded but not yet attached). Janitor sweeps staged assets past the 24h TTL.
filenameOriginal filename as supplied by the user. Never appears in
storageKey.mime_type: RFC 6838 type/subtype.size_bytes: Verified at complete-upload time againstHeadObject.contentLength.storage_keyObject-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_signatureEngine 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_attemptsNumber of scan attempts so far (inline at complete-upload plus sweep retries). Drives the retry sweep's exponential backoff.
scanned_atWhen 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_atWhen 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_atWhen 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_byfk 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_atSoft-delete marker. Janitor sweeps R2 object + hard-deletes after 24h.
public_link_enabled1667, 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:
idUUIDv7 from
node.yamlwhen supplied by the importer (stable across moves); falls back tocuid()for inserts that omitid.memory_id:node_type: See the node-types list in the model doc. Defaultinfo.object_type725 — 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_placeholder1450 — 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:abstractParagraph-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-fallbackmarker onhadron_get_nodecontent-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_hashSHA256(yaml+md)[0:8] for change detection. Set by external producers (YAML frontmatter via importer, Git sync). UNCHANGED by spec 032 — that spec adds
abstractOriginHashbelow as a separate column with its own domain (SHA256(content)[0:8]); the two are never compared against each other.abstract_origin_hashSpec 032 — fingerprint of
contentvalue at the timeabstractwas authored. SHA-256 of plaintext content truncated to 8 hex chars (same width ascontentHash, different domain). At read time, compared againstcomputeContentHash(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 byhadron_get_node'sSource: abstract-stalemarker andhadron_validate's[stale-abstract]warning. System-managed: never settable via GraphQLNodeInput.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
!= nullguard. The published Data Model reference is generated from this comment, so it contradicted the GraphQL reference for the whole gap.embedding_pending_atSet 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_tokeninternal#4: opaque identity of one durable obligation; time only schedules it. Operational, never copied into revisions or approval/authorship state.
embedding_failed_atSet 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.dataStructured JSON on the node; used for template-variable resolution, user profiles, extracted facts, reference metadata. Returned by
hadron_get_node; written byhadron_update_node(replaces the bag) orhadron_update_node_data(shallow merge).seqSort order among sibling nodes (lower values come first); used by
hadron_get_next_nodeand portal drag-and-drop reordering.message_channel_id1430 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.role1201 — 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:01lists node TYPES and node ROLES as separate categories, and the roles (chat, chat-message, config, …) live innodeTypetoday. Migrating those offnodeTypeis deliberately NOT part of #1201 — live consumers includeisChecklistItemListing, the chat surfaces andpreflight_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_modelLLM model that created or last modified this node (e.g. "claude-opus-4-6", "gpt-4o").
ai_agentAI agent tool that created or last modified this node (e.g. "claude-code", "cursor", "hadron-portal").
authorship_kind1326 — 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_seq696/#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_seq1611 (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_hashtrigger on the same 'refresh' marker asrevisionContentHash. An approval recorded atapprovedRevNois still valid iffcontentRevSeq <= approvedRevNo: metadata-only revisions advancerevSeqbut not this. A write outside the revision system never moves it, so such a change stays TAMPERED.revision_content_hash1323: 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_no1591 — 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.approvedByis a User.id when one is known, with no FK so a user deletion cannot rewrite who approved; otherwiseapprovedByInfoholds the principal (the NodeRevision.editedByInfo convention).approvalHashis 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 thatapprovalHashalone 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_at1591 — per-node minting. A node is minted iff
mintedAtis 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/mintedHashrecord that revision and its approval hash; both are null for nodes backfilled as minted by the #1591 migration, whose minted revision is unknown.mintedByis a User.id (no FK, likeapprovedBy), elsemintedByInfoholds 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_at1632 / 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_id1610 — 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_id2176 — 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 validatedauth.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 before2176 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_idDenormalized 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".modelStored 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_idDenormalized from the SOURCE node's memory so
loccan 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:locColon-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 (seesrc/lib/edgeLoc.ts). MirrorsNode.loc.nameFree-form relationship name (e.g. imports, depends_on, abstract-of). Optional since spec-037 —
locis now the identity. (Waslabel.)description: Human-readable description of the edge (parity withNode.description).is_runnableIf true, this edge can be executed/run (task automation, conversation transitions). Mirrors
Node.isRunnable.conditionJSONLogic 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 builtinsnow()andtoday()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/.priorityResolution-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.
dataFree-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_kind1606 (
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_noThe target revision a top-level comment was written against. Set iff
governedKind = COMMENT_ANCHOR(CHECKchk_edges_governed_anchor).anchor_approval_hashcomputeApprovalHashof the target's title/abstract/content ATanchorRevNo(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_idThe commented node. Immutable.
ON DELETE CASCADEonly 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_keyThe author (
cor:dmo:110:03):w:<workerId>,ua:<userId>:<agentId>,u:<userId>orapp:<appId>. Immutable.retracted_at1721 — 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 (theauthorKeygrammar) of whoever deleted the comment.resolved_at:resolved_by:thread_deleted_atMirrors 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_causeADMIN(deleteCommentThread),AUTHORorMANAGER(#1721 deleteComment, by its author or by a memory manager), orTARGET(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_idIntended target node id — NOT a foreign key; resolved at promotion time.
locEdge 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 (waslabel).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_idThe User this session is attributed to (typically the end-user in a chatbot/automation session; the developer in a DEVELOPER session).
agent_idThe Agent driving the session (NULL for free-form developer sessions not tied to a specific Agent). When
workerIdis set this records the ROLE-agent behind the casting (cor:agt:020:03).worker_id974 — 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.
role2458 (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_idThe active write-memory for this session, when there's an unambiguous one. Resolves the multi-writable-memory ambiguity.
expires_atHard 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_path928 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", ...).family1707 — the model family this session runs as (cor:agt:060:04): given¶
at session start, or derived from
llmModelthentool; 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_at2252 — when
llmModelwas 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_id1709 (cor:agt:070:08; Holger via Vera #10773) — a host-launched session:¶
the host that started it, the
worker.startoperation, 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_idChain 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_atSet 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 dropsupdatedAton an auto-expired row (the reap overwrote it). Always written together withendedAtand to the same instant, so "ended" stays the single predicateendedAt IS NOT NULLand this column records only HOW it ended. (#1232 — this readIS 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_idMemory 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 allSetNull, and memory-scoped analytics used to reach the memory by joining throughnode, so deleting a node silently erased the event from its memory's history. ASetNullFK 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 whentype = 'action-run'.model: LLM model used for this specific event.tokens_in: Input tokens consumed.tokens_out: Output tokens generated.user_idThe on-behalf-of user (billing attribution). Nullable — pure-App service runs have no user. Distinct from the audit
createdBystring.organization_idThe billable organization. Set on every metered event so ledger attribution never needs a join through App.
providerLLM provider that served the call —
modelalone is ambiguous across providers (e.g. claude via anthropic vs bedrock).key_owner_typeAiConfigOwnerType 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_centsProvider 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_activity1653 / 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_tasks2138 §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_task2162 (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_idUser owner of a user-owned Agent (rooted on the bare
<handle>— #697 v2, no@sigil). The org/owner XOR is ENFORCED —chk_agent_owner_xorin post-push.sql:(organization_id IS NULL) <> (owner_user_id IS NULL)— so exactly one oforganizationId/ownerUserIdis non-null.urnGlobally unique identifier (e.g. "micromentor.org:juno"); derived from
org.urn + ":" + slug.name: Display name of this agent.description:boot_prompt_node_id2045 (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.bootPromptUrnis 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 throughsetBootPromptPointer(src/lib/bootPromptPointer.ts).boot_prompt_urn:system_memory_idMemory 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.
visibilityPUBLIC | ORGANIZATION | PERSONAL (035-visibility-enum-cleanup gave agents their own enum). PERSONAL is the creator-only draft state.
listed_on_marketplaceOpt-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.typeCoarse behavior hint — see AgentType enum doc. Largely legacy post-008.
surfacesSurfaces 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_locLoc of the currently-published revision of the Agent's system memory. Lets the Builder ship draft revisions without affecting running Apps.
editor_lock_user_idOptimistic 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).propertiesAgent working state (per-user data like family budget, preferences); automatically available to the LLM as context.
memory_provisioningDeclares how this Agent expects per-App memory to be provisioned. Shape:
{ appMemory: 'shared' | 'user' | 'none' }.personalMemoryprovisioning is implicit (lazy-create on first user-attributed write). 008-agent-installation FR-008.register_defaultsSpec 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_policyDeclares membership constraints for any App that installs this Agent. Shape:
{ maxMembers: number | 'unlimited', memberRoles: string[] }.maxMembersenforced at AppMember invite-acceptance time. 008-agent-installation FR-009.persona_rolePersona role — free string with conventions ("backend-engineer"). A dedicated column so roster/casting queries can filter without parsing the prompt.
extends_agent_id1885 (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 byagent_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_ref1892 (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_ref1892 (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_atOnline 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_reasonSpec 021 sentinel for data-defect rows during the FR-032 migration. TODO(spec-021-cleanup): drop alongside urnNormalizedAt.
legacy_urn697 stored alias map: the pre-v2 (v1) URN this row was migrated FROM¶
(see Memory.legacyUrn). Null until the online migration flips
urnto 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_typeColumn 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.activatedIf 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:roleColumn type is the full
Roleenum, but the intended grant set isCONTRIBUTOR | READER(reader = read-only, contributor = read-write). Tightening reserved for a future cleanup spec.activatedIf 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_idThe 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:providerProvider 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_encryptedAES-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.paramsProvider-specific knobs (maxTokens, thinking, effort, baseUrl, ...). Validated per provider by zod in src/lib/aiConfig.ts.
endpoint1373: 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_style1373 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).roleColumn type is the full
Roleenum, but the intended grant set isADMIN | 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_idfk 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_roleColumn type is the full
Roleenum, but the intended set isADMIN | null(most invites grant no global role).member_roleColumn type is the full
Roleenum, but the intended grant set isADMIN | CONTRIBUTOR | READER.new_user_idfk to User.id — set when the invitation is accepted and a User is created.
name: Recipient's name.email:github_username:phone_number:max_activationsMaximum number of times this invitation can be accepted by a new recipient; current count is determined from UserInvitationActivation rows.
expires_at:accepted_atWhen 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_hash505 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_idMemory 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:abstractParagraph summary at the time of the snapshot. Spec 031. Added in the US1 implementation when the live
Node.abstractcolumn landed — revision history would otherwise silently drop abstract edits.abstract_origin_hashRevision snapshot of
Node.abstractOriginHashat capture time (cor:dmo:020:03, cor:dmo:060:02). Restored verbatim byrestoreNodeRevision. 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:role1201 —
Node.roleat 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_kind1326 — 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_by620: 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 toeditedByInfo, rationales torevLabel, and backfilled fromcreatedBywhere that held a User id.edited_by_info620: 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_id1610 — 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_label620: user-settable label for this revision (updateNodeRevision¶
mutation; REV_LABEL_MAX_LEN cap). Also captures the #88
reasonarg at snapshot time — the edit rationale that previously squatted ineditedBy(legacy reasons were migrated here).changes620: which node fields the edit that took this snapshot changed¶
(e.g. ["abstract","tags"]). The snapshot itself is the PRE-edit state, so
changesdescribes the delta between this snapshot and the state that replaced it. Empty for legacy rows (NULL reads as []).approved_by620/#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_no696: per-node MONOTONIC revision number (1, 2, 3, …) — the stable atom¶
in the
hrn:noderev:<root>:<mem>:<loc...>:<rev>URN (renderedr<N>). Minted race-safely fromNode.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_idSnapshot 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_emailThe 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:providerEmail provider backing this connection — the emailClient dispatch key (#396: one capability tool per provider; 'ms-exchange' today).
tool_connection_idThe 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_encryptedLEGACY (#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_enabledSoft 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_atSubscription 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(neverfindUnique). - 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).scopesOperation 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:actionsAllowed 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_idThe 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_idThe 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_idThe resolved
Secretrow 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:slugRun-tool name segment (
mcp__<slug>__<tool>); lowercase [a-z0-9-], unique per org. Keep it short — provider tool-name caps are ~64 chars.name:urlStreamable-HTTP MCP endpoint URL. The conduit refuses private-network hosts unless explicitly allowed (SSRF guard, dev only).
headers_encryptedAES-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.enabledDisabled 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:metadataThe 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_encryptedencryptToken(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_idKey-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:slugRun-tool name segment (
ha__<slug>__<op>); lowercase [a-z0-9-], unique per org. Keep it short — provider tool-name caps are ~64 chars.name:urlHome 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_encryptedAES-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_allowlistExposed-op allowlist over the closed HA_OPS catalog; empty = every op. Lets an admin register a READ-ONLY instance (no call_service).
enabledDisabled 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_addressFixed sender identity accepted by Resend, e.g.
Hadron Agent <agent@example.com>. Not secret.api_key_encryptedAES-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.policyApp-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.
urnGlobally 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@uniquedeclaration 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; thefindUniquecallers inresolvers.tswere migrated to this pattern in PR #124.organization_id:owner_user_idUser owner of a user-owned App (rooted on the bare
<handle>— #697 v2, no@sigil). The org/owner XOR is ENFORCED —chk_app_owner_xorin post-push.sql:(organization_id IS NULL) <> (owner_user_id IS NULL)— so exactly one oforganizationId/ownerUserIdis non-null.create_user_permission:identify_user_method:session_timeout_seconds:session_dormancy_daysRuling 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_expireRuling DY-3: whether
startAgentSessionstamps a hardexpiresAtby default. False = this App's agent sessions have NO hard expiry unless the call asks for one (a caller-suppliedsessionTimeoutSeconds, still capped by the App ceiling). A forgotten one is still bounded: past the App'ssessionDormancyDaysit no longer binds (bindSession, DY-5).anonymous_ttl_days:ticker_min_cadence_secondscor: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 CHECKchk_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_seconds2138 §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_seconds2755 — 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_at2138 §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).properties3125 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 reservedtaskIntegrationskey (cor:agt:120:01). NULL = no properties. CHECK: an object when set.properties_revision3125 S1 (V34): moved by every changing
setAppPropertieswrite, 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_typeDeprecated — superseded by
surfaces. Scheduled for removal in a follow-up cleanup spec (per 008 R-4); kept in place to avoid spurious portal churn.roleDefault member role applied when the Agent's
installation_policy.memberRolesdoesn't apply.description:agent_tools: Tools this App's agent can access; default[].expires_at:training_modeMigrated 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.surfacesFree-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 readssurfaces.includes('chat'). 008-agent-installation FR-014.created_at:created_by:updated_at:updated_by:deleted_at:deleted_by:uninstalled_atSoft-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_atOnline 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. Theapps_urn_migration_pending_idxpartial index goes with it.urn_migration_failed_reasonSpec 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_urn697 stored alias map: the pre-v2 (v1) URN this row was migrated FROM¶
(see Memory.legacyUrn). Null until the online migration flips
urnto v2.default_channel_idSpec 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 livechats:teamroot, 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 rawhdr_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:roleFree-form string validated at write-time against the parent Agent's
installation_policy.memberRoles(per 008 R-7). Examples:'owner','guide','cook'.installation_policy.maxMembersis 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_atSet 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_idThe Agent that does the importing (the "Suite"). ON DELETE CASCADE.
imported_agent_idThe dep Agent. ON DELETE RESTRICT — deleting it would invalidate every Suite that depends on it; operators must remove the import edge first.
positionSparse-int ordering (per 008 R-8). Builders set values like 100, 200, 300 to allow easy reordering without renumbering.
required: Hard dep vs optional. Defaulttrue.agent_org_grant_org_idComposite fk to
AgentOrgGrant(orgId, agentId)(ON DELETE RESTRICT) — the Builder grant authorizing this import. Spec FR-005 named this columnagent_subscription_id; renamed per 008 R-2 since the universal-grant role for org-level grants lives on the newAgentOrgGrantsibling, notAgentSubscription.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_atv1 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_atSet 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_id2045 (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.bootPromptUrnis 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 throughsetBootPromptPointer(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.slug991 — the URN atom:
hrn:worker:<root>:<app-slug>:<slug>. DERIVED from¶nameat 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.roleThe cast-list role this filling answers ("backend-engineer"). Free string with conventions; defaults to the agent's
personaRoleat 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_id2045 (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.bootPromptUrnis 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 throughsetBootPromptPointer(src/lib/bootPromptPointer.ts). Set for customised workers only, empty otherwise (cor:dmo:050:11).boot_prompt_urn:memory_id974 — 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_id1050 — 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_atWhen 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 withheldByUserId, 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.heldAttherefore 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_atRetirement 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_id1726 — 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 theworker.reports-toevent that keeps its history.explicit_no_team: S12: explicit human choice; false + null reportsTo is UNSET, never inferred NO_TEAM.terminal2771 (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 nocheckStatus, 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 behindmaySeeWorkerInternals(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 rawhdr_user_<…>key.key_preview: Last 4 characters of the raw key for masked display.label: Human-friendly name for this key.created_at:created_byActor that minted this key. Schema-wide convention:
User.idof the actor. For self-service v1 this equalsuserId; the column exists for future admin-issued paths (where actor != owner).issued_viaIssuance 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_scopesImmutable 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_at2298: the owner hid this REVOKED key from their default list. Display¶
state only: never read by authentication, revocation or lineage.
minted_by_key_idAuthenticated 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_id1897 / 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.reasonOptional support/diagnostic reason supplied at start. Capped at the resolver (USER_API_KEY_LABEL_MAX_LEN precedent).
created_at:expires_at:ended_atExplicit-stop timestamp. NULL while live or when the session merely lapsed by TTL.
ended_byUser.idof 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_idThe public client identifier. DCR-registered:
dcr_<32 hex>(16 bytes / 128 bits). Seeded fixtures use stable identifiers like'test'. Primary key.client_name:redirect_urisAllowed 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_at155: 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_hashSHA-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).resourceRFC 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_scopesImmutable 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_byActor that initiated the /authorize request that minted this code. Resolves to the signed-in User; equals
userIdin self-service v1.sign_in_id1897: 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_id1631 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_idThe 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 iscompletedByPasskeyId.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 | withdrawncreated_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_idThe 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_hashlogin+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:
stateThe OAuth
stateCSRF 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_state477 session-fixation binding — the portal's browser nonce, stamped¶
onto the login handoff code at the callback.
ceremony_nonce_hash1631 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_hash2204: SHA-256 of the OIDC
noncesent 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 fromclient_stateandceremony_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_idOn-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_id2438: 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:dataRun 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).eventDatastays the immutable trigger payload; on key collision the envelope wins.hopsPer-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+failureidentify it.derived_log2047 (S10, cor:agt:040:03): the derived blocks each hop of the run saw, append-only,
[{hop, blocks}], where¶blocksis 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 nohopselement) 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.spawnPARENT-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_initial832 — the budget this run was MINTED with, so a client can render¶
"spent vs budget".
budgetTokensabove is what REMAINS. NULL on runs minted before the column existed.budget_actions_initial:tokens_spent832 — cumulative spend, incremented in the same write as the budget¶
decrement. Deliberately NOT derived: * a
hopssum under-reports — a hop that failed mid-execution has no element, which is exactly the run an operator is auditing; *initial - remainingunder-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_spentis backfilled from the hop trail where one exists;actions_spenthas 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_cents2439 — 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_snapshotSpec 049 Phase 3b (D-2026-09-13-004): the trigger's scope, SNAPSHOTTED at mint as its ordered memory-id list (as
policyis 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_snapshotSpec 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:cron5-field cron expression, evaluated in
timezone— recurring schedules. XOR withrunAt(chk_agent_schedule_cron_xor_run_at).timezone:run_atOne-shot: run once at this instant (#510). XOR with
cron; the scheduler claim flipsenabledto false instead of advancingnextRunAt. Misfire policy unchanged (overdue runs once).automation_pin: #1719 R5b: owner-adopted complete graph; NULL fails closed at execution.entry_node_urn:entry_node_id2438: 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_atNext 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:tierPricing 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_pointsMarkup 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_typeProvenance: 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_id2438: 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_keyCaller-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_idThe active memory selection, stored as the PK rather than the URN so a rename cannot strand it. The URN is resolved on read.
organization_idSpec 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 fromappIdat 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_idSpec 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:urnThe 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_urnThe 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:position0-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:incarnationMonotonic 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_defaultD2 — 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_at2138 §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_incarnation2181 — the Channel incarnation the stored cursor was last RAISED under. Written by
advanceReadStatein 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_id1334 — 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.revisionOptimistic-concurrency counter (#1325, cli#716 Q1): starts at 1, +1 on every update; a mutation passing
expectedRevisionrefuses 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:revisionOptimistic-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_hashAPPROVE: 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_number2553: 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 projectAT0("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.handle2553: 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_id3125 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_id2646 (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:properties2420 (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_by2648 (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_code2651 (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_references2649 (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_doneSet 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_id1756 (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_idWho 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_id3132 (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_id3132 (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_start1706 — 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
taskIdandtype(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_at2200 (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_atstay 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, typealarm.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_id1709 — the host whose key set this record (
setBy = hostonly), so a¶host clears only its own marks (cor:agt:060:08).
clears_on_activity_after2162 (cor:agt:050:27) — a
resettingmark 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_id2162 (cor:agt:050:27) — a
resettingmark 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_ins1763 (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_minutes1709 (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_minutes1881 (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:capabilities2162 (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:worktrees1709 — 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_id1709 slice 2 (#1883 review, Diego P2-1) —
worker.startonly: 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_idThe 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: Thetask.session-end-requestedevent 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:actionregister|collect|report|availability|read(#1881: the App's host registrations or host-operations listing, read with the key;2931: its host's tickers,
countthe rows returned) |¶session(#1969: a refused session write; always carries a refusedCode).operation_id:count:refused_code1881 (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'.reasons2068 (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_id2024 (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;
generatedForWorkerIdis 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_at2429 (cor:dmo:050:11): set by every accepted
updateTickeron 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_untilS7 (#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_at2755 — 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_idWho 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_at3022: 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_keyWhich 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_keys2069: 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_id1709 — the one host a
host:operatescope 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: whileleaseUntilis in the future only the holder ofclaimTokenis 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_seqThe 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 onlyTARGET_HARD_DELETED.removed_by: Same valueNode.deletedBywould carry (user, app or client id), null when unattributed.created_at:
asset_public_link_audits¶
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: