@ai-matrx/associations 0.5.2 → 0.6.0

package/dist/CommentThread-D4kcTbog.d.cts

@@ -0,0 +1,1905 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, ElementType, SVGProps } from 'react';
+
+/** Per-RPC Args/Returns for every demanded function, straight from the live DB. */
+interface DemandedRpcSignatures {
+    assoc_add: {
+        Args: {
+            p_label?: string;
+            p_metadata?: unknown;
+            p_org_id?: string;
+            p_payload?: unknown;
+            p_payload_kind?: string;
+            p_position?: number;
+            p_role?: string;
+            p_source_id: string;
+            p_source_type: string;
+            p_target_id: string;
+            p_target_type: string;
+        };
+        Returns: string;
+    };
+    assoc_remove: {
+        Args: {
+            p_role?: string;
+            p_source_id: string;
+            p_source_type: string;
+            p_target_id: string;
+            p_target_type: string;
+        };
+        Returns: undefined;
+    };
+    assoc_set_targets: {
+        Args: {
+            p_org_id?: string;
+            p_role?: string;
+            p_source_id: string;
+            p_source_type: string;
+            p_target_ids: string[];
+            p_target_type: string;
+        };
+        Returns: undefined;
+    };
+    assoc_remove_for_entity: {
+        Args: {
+            p_id: string;
+            p_type: string;
+        };
+        Returns: undefined;
+    };
+    assoc_for_entity: {
+        Args: {
+            p_id: string;
+            p_type: string;
+        };
+        Returns: {
+            created_at: string;
+            direction: string;
+            id: string;
+            label: string;
+            metadata: unknown;
+            organization_id: string;
+            other_id: string;
+            other_type: string;
+            position: number;
+            role: string;
+        }[];
+    };
+    assoc_for_targets: {
+        Args: {
+            p_target_ids: string[];
+            p_target_type: string;
+        };
+        Returns: {
+            created_at: string;
+            id: string;
+            label: string;
+            metadata: unknown;
+            organization_id: string;
+            position: number;
+            role: string;
+            source_id: string;
+            source_type: string;
+            target_id: string;
+        }[];
+    };
+    assoc_for_sources: {
+        Args: {
+            p_source_ids: string[];
+            p_source_type: string;
+            p_target_type?: string;
+        };
+        Returns: {
+            created_at: string;
+            id: string;
+            label: string;
+            metadata: unknown;
+            organization_id: string;
+            position: number;
+            role: string;
+            source_id: string;
+            target_id: string;
+            target_type: string;
+        }[];
+    };
+    assoc_members_visible: {
+        Args: {
+            p_target_ids: string[];
+            p_target_type: string;
+        };
+        Returns: {
+            created_at: string;
+            id: string;
+            label: string;
+            metadata: unknown;
+            organization_id: string;
+            position: number;
+            role: string;
+            source_id: string;
+            source_type: string;
+            target_id: string;
+        }[];
+    };
+    conversation_file_add: {
+        Args: {
+            p_conversation_id: string;
+            p_file_id: string;
+            p_label?: string;
+            p_metadata?: unknown;
+            p_replace_metadata?: boolean;
+        };
+        Returns: string;
+    };
+    conversation_file_remove: {
+        Args: {
+            p_conversation_id: string;
+            p_file_id: string;
+        };
+        Returns: undefined;
+    };
+    conversation_files: {
+        Args: {
+            p_conversation_id: string;
+        };
+        Returns: {
+            created_at: string;
+            file_id: string;
+            label: string;
+            metadata: unknown;
+        }[];
+    };
+    agent_resource_add: {
+        Args: {
+            p_agent_id: string;
+            p_label?: string;
+            p_metadata?: unknown;
+            p_source_id: string;
+            p_source_type: string;
+        };
+        Returns: string;
+    };
+    agent_resource_remove: {
+        Args: {
+            p_agent_id: string;
+            p_source_id: string;
+            p_source_type: string;
+        };
+        Returns: undefined;
+    };
+    cat_list: {
+        Args: {
+            p_dimension?: string;
+        };
+        Returns: {
+            color: string;
+            dimension: string;
+            icon: string;
+            id: string;
+            is_system: boolean;
+            metadata: unknown;
+            name: string;
+            organization_id: string;
+            parent_id: string;
+            position: number;
+            slug: string;
+        }[];
+    };
+    cat_create: {
+        Args: {
+            p_color?: string;
+            p_dimension: string;
+            p_icon?: string;
+            p_name: string;
+            p_org_id: string;
+            p_parent_id?: string;
+            p_slug?: string;
+        };
+        Returns: string;
+    };
+    cat_update: {
+        Args: {
+            p_category_id: string;
+            p_color?: string;
+            p_icon?: string;
+            p_name: string;
+            p_position?: number;
+            p_slug?: string;
+        };
+        Returns: string;
+    };
+    cat_reparent: {
+        Args: {
+            p_category_id: string;
+            p_parent_id?: string;
+        };
+        Returns: string;
+    };
+    cat_delete: {
+        Args: {
+            p_category_id: string;
+        };
+        Returns: string;
+    };
+    ues_set: {
+        Args: {
+            p_entity_id: string;
+            p_entity_type: string;
+            p_is_favorite?: boolean;
+            p_is_hidden?: boolean;
+            p_is_pinned?: boolean;
+        };
+        Returns: undefined;
+    };
+    ues_list: {
+        Args: {
+            p_kind?: string;
+        };
+        Returns: {
+            entity_id: string;
+            entity_type: string;
+            is_favorite: boolean;
+            is_hidden: boolean;
+            is_pinned: boolean;
+            last_viewed_at: string;
+            updated_at: string;
+        }[];
+    };
+    ues_get_bulk: {
+        Args: {
+            p_entity_ids: string[];
+            p_entity_type: string;
+        };
+        Returns: {
+            entity_id: string;
+            is_favorite: boolean;
+            is_hidden: boolean;
+            is_pinned: boolean;
+            last_viewed_at: string;
+        }[];
+    };
+    ues_touch: {
+        Args: {
+            p_entity_id: string;
+            p_entity_type: string;
+        };
+        Returns: undefined;
+    };
+    reference_search_candidates: {
+        Args: {
+            p_ids?: string[];
+            p_limit?: number;
+            p_search?: string;
+            p_token: string;
+        };
+        Returns: {
+            id: string;
+            title: string;
+        }[];
+    };
+    cmt_list: {
+        Args: {
+            p_entity_id: string;
+            p_entity_type: string;
+        };
+        Returns: {
+            author_avatar_url: string;
+            author_display_name: string;
+            author_email: string;
+            body: string;
+            created_at: string;
+            created_by: string;
+            entity_id: string;
+            entity_type: string;
+            id: string;
+            organization_id: string;
+            parent_id: string;
+            updated_at: string;
+        }[];
+    };
+    cmt_add: {
+        Args: {
+            p_body: string;
+            p_entity_id: string;
+            p_entity_type: string;
+            p_org_id?: string;
+            p_parent_id?: string;
+        };
+        Returns: string;
+    };
+    cmt_edit: {
+        Args: {
+            p_body: string;
+            p_id: string;
+        };
+        Returns: undefined;
+    };
+    cmt_delete: {
+        Args: {
+            p_id: string;
+        };
+        Returns: undefined;
+    };
+}
+/** The name of any demanded RPC — the only strings the dataSource port accepts. */
+type DemandedRpcName = keyof DemandedRpcSignatures;
+
+/**
+ * EVERY registered entity token (the FK-valid set). Use this for any
+ * `source_type` / `target_type` argument so an invalid token is a COMPILE error.
+ */
+type EntityTypeToken = "access_request" | "activity" | "agent" | "agent_card" | "agent_definition_version" | "agent_drift_alert" | "agent_exemplar" | "agent_mandate_note" | "agent_prompt_remediation" | "agent_run" | "agent_run_stage" | "agent_shortcut" | "agent_surface_binding" | "agent_template" | "agent_usage" | "ai_api" | "ai_endpoint" | "ai_model" | "ai_model_alias" | "ai_offering" | "ai_provider" | "ai_setting" | "app" | "app_definition_version" | "app_error" | "app_execution" | "app_instance" | "app_log" | "app_rate_limit" | "app_setting" | "app_sync_status" | "approach" | "artifact" | "assessment" | "assessment_item" | "assessment_result" | "assist" | "batch_cost_event" | "batch_provider_batch" | "batch_work_item" | "browser_account_binding" | "browser_action_event" | "browser_authenticator_window" | "browser_capture" | "browser_control_request" | "browser_handoff" | "browser_login_attempt" | "browser_login_recipe" | "browser_profile" | "browser_profile_checkpoint" | "browser_run" | "browser_site_observation" | "browser_site_policy" | "browser_stream_ticket" | "canvas_comment" | "canvas_comment_like" | "canvas_item" | "canvas_item_state" | "canvas_like" | "canvas_score" | "canvas_view" | "category" | "cmp_entry" | "cmp_feedback" | "code_file" | "code_folder" | "code_repository" | "coding_session" | "coding_session_entry" | "comment" | "commerce_asset_allocation" | "commerce_asset_grading" | "commerce_asset_identifier" | "commerce_asset_lot_event" | "commerce_asset_mandate_result" | "commerce_asset_price_factor" | "commerce_asset_reshoot_request" | "commerce_asset_review" | "commerce_asset_unknown" | "commerce_cloud_sync_connection" | "commerce_ebay_business_policy" | "commerce_ebay_category" | "commerce_ebay_category_aspect" | "commerce_ebay_category_tree" | "commerce_ebay_custom_policy" | "commerce_ebay_inventory_item" | "commerce_ebay_inventory_item_group" | "commerce_ebay_inventory_item_group_member" | "commerce_ebay_inventory_location" | "commerce_ebay_listing" | "commerce_ebay_marketplace_policy" | "commerce_ebay_media_asset" | "commerce_ebay_notification_destination" | "commerce_ebay_notification_event" | "commerce_ebay_notification_subscription" | "commerce_ebay_notification_topic" | "commerce_ebay_offer" | "commerce_ebay_order" | "commerce_ebay_order_line_item" | "commerce_ebay_shipping_fulfillment" | "commerce_ebay_store_category" | "commerce_human_correction" | "commerce_intake_artifact" | "commerce_intake_asset" | "commerce_intake_batch" | "commerce_label_batch" | "commerce_label_code" | "commerce_marketplace_account" | "commerce_marketplace_account_deletion_audit" | "commerce_marketplace_api_call" | "commerce_marketplace_rate_budget" | "commerce_marketplace_site" | "commerce_marketplace_sync_run" | "commerce_prediction_outcome" | "commerce_product" | "commerce_product_channel_ref" | "commerce_product_media" | "commerce_product_variant" | "commerce_recall_audit" | "comparison_set" | "contact_medium" | "contact_submission" | "content_ir_kind" | "content_ir_kind_component" | "content_ir_kind_component_incident" | "content_ir_kind_conformance" | "content_ir_kind_edge" | "content_ir_kind_example" | "content_ir_kind_instance" | "content_ir_kind_surface" | "context_item" | "context_item_suggestion" | "conversation" | "conversation_value" | "crm_address" | "crm_affiliation" | "crm_blocklist_entry" | "crm_contact_candidate" | "crm_deal" | "crm_deal_stage_event" | "crm_enrichment_call" | "crm_interaction" | "crm_merge_candidate" | "crm_outreach_list" | "crm_outreach_list_member" | "crm_party_merge" | "crm_registry_ingest_run" | "crm_registry_source" | "crm_saved_view" | "crm_sending_event" | "crm_sending_identity" | "crm_sending_identity_check" | "crm_sending_policy" | "custom_entity_definition" | "custom_field_definition" | "custom_field_target" | "custom_record" | "cx_agent_memory" | "cx_agent_plan" | "cx_agent_task" | "cx_code_edit" | "cx_code_message_file" | "cx_media" | "cx_observational_memory" | "cx_observational_memory_event" | "cx_pending_injection" | "cx_request" | "cx_request_snapshot" | "cx_tool_trace" | "cx_user_request" | "cx_user_todo" | "data_store" | "dataset" | "derive_run" | "dict_setting" | "dm_conversation" | "dm_message" | "dm_participant" | "domain_classification" | "esign_campaign" | "esign_campaign_member" | "esign_consent_disclosure" | "esign_envelope" | "esign_envelope_certificate" | "esign_envelope_document" | "esign_envelope_event" | "esign_envelope_external_ref" | "esign_envelope_signer" | "esign_provider" | "esign_provider_binding" | "esign_signing_key" | "fc_card" | "fc_detail" | "fc_set" | "feature_doc" | "file" | "file_analysis" | "file_entities" | "file_overrides" | "file_page_annotations" | "file_pages" | "file_version" | "flexible_data" | "folder" | "game_badge" | "game_result" | "game_room" | "global_execution" | "global_execution_checkpoint" | "global_execution_event" | "global_meter_entry" | "global_origin" | "global_request" | "growth_loop_event" | "growth_loop_run" | "growth_loop_stage_run" | "guided_checklist_run" | "heatmap_save" | "hindsight_enrollment" | "hindsight_finding" | "hindsight_regression_case" | "hindsight_replay" | "hindsight_replay_step" | "hindsight_review" | "hr_access_audit" | "hr_access_role" | "hr_accommodation_request" | "hr_ai_evidence" | "hr_alert_routing_rule" | "hr_application" | "hr_approval_authority" | "hr_approval_delegation" | "hr_asset" | "hr_asset_assignment" | "hr_attendance_exception" | "hr_auto_close_rule" | "hr_availability" | "hr_background_check" | "hr_benefits_event" | "hr_calculation_snapshot" | "hr_candidate" | "hr_candidate_conversion" | "hr_candidate_message" | "hr_careers_portal" | "hr_checklist_item" | "hr_checklist_run" | "hr_checklist_template" | "hr_checklist_template_item" | "hr_compensation" | "hr_corrective_action" | "hr_course" | "hr_course_version" | "hr_credential" | "hr_crew" | "hr_deduction_code" | "hr_department" | "hr_derived_grant" | "hr_disposition_event" | "hr_earning_code" | "hr_eeo_response" | "hr_emergency_contact" | "hr_employee" | "hr_employee_private" | "hr_employer_profile" | "hr_employment" | "hr_employment_pin" | "hr_engagement" | "hr_establishment" | "hr_external_identity" | "hr_field_policy" | "hr_holiday" | "hr_holiday_calendar" | "hr_i9" | "hr_i9_document" | "hr_incident" | "hr_incident_party" | "hr_interview" | "hr_interview_kit" | "hr_job_title" | "hr_jurisdiction" | "hr_jurisdiction_rule" | "hr_jurisdiction_rule_class" | "hr_jurisdiction_rule_org_decision" | "hr_jurisdiction_rule_test" | "hr_kiosk_device" | "hr_kiosk_session" | "hr_labor_target" | "hr_leave_case" | "hr_leave_enrollment" | "hr_leave_ledger" | "hr_leave_policy" | "hr_leave_request" | "hr_legal_hold" | "hr_legal_hold_item" | "hr_location" | "hr_new_hire_report" | "hr_offer" | "hr_opening" | "hr_overtime_alert" | "hr_overtime_alert_rule" | "hr_overtime_preapproval" | "hr_pay_group" | "hr_pay_period" | "hr_pay_period_employment" | "hr_payroll_export" | "hr_payroll_export_line" | "hr_position_assignment" | "hr_posting" | "hr_posting_publication" | "hr_provider_binding" | "hr_provider_event" | "hr_provisioning_result" | "hr_punch" | "hr_recalculation_batch" | "hr_record_class" | "hr_records_request" | "hr_reference_check" | "hr_reporting_line" | "hr_requisition" | "hr_restricted_note" | "hr_retention_rule" | "hr_role_assignment" | "hr_schedule" | "hr_schedule_change" | "hr_schedule_guidance" | "hr_schedule_template" | "hr_schedule_template_shift" | "hr_scorecard" | "hr_separation" | "hr_shift" | "hr_shift_claim" | "hr_staffing_requirement" | "hr_survey" | "hr_survey_invitation" | "hr_survey_question" | "hr_survey_response" | "hr_tax_registration" | "hr_tax_withholding" | "hr_time_adjustment" | "hr_training_assignment" | "hr_training_attempt" | "hr_transcript_entry" | "hr_verification_letter_request" | "hr_work_interval" | "hr_workflow_binding" | "hr_workflow_decision" | "hr_workflow_definition" | "hr_workflow_event" | "hr_workflow_failure" | "hr_workflow_flow_type" | "hr_workflow_instance" | "hr_workflow_step" | "hr_workflow_step_definition" | "hr_workweek" | "iam_api_key" | "industry_curator" | "interview_document_revision" | "interview_hole" | "interview_question" | "interview_session" | "interview_turn" | "invitation" | "invitation_code" | "invitation_request" | "item_mastery" | "judge_verdict" | "kg_alert" | "kg_suggestion_ack" | "kg_sweep_queue" | "kg_sweep_run" | "kg_sweep_state" | "kg_value_match" | "league_membership" | "learn_doc" | "library_doc" | "mandate" | "mandate_binding" | "mandate_treatment" | "marketing_initiative" | "masterwork_corpus_item" | "masterwork_run" | "membership" | "message" | "message_template" | "ner_shadow" | "note" | "note_folder" | "notification" | "notification_channel_preference" | "notification_event_override" | "notification_event_type" | "notification_preference" | "ops_issue_event" | "ops_proof_check" | "ops_proof_run" | "ops_proof_scenario" | "organization" | "output_feedback" | "page_extraction_job" | "page_extraction_page_run" | "party" | "party_contact_point" | "pc_article" | "pc_episode" | "pc_show" | "pc_studio_run" | "pc_studio_run_asset" | "pdf_redaction_audit" | "plan_cms_fill_item" | "plan_cms_fill_job" | "plan_entity" | "plan_node" | "plan_node_artifact" | "plan_node_step" | "plan_profile" | "platform_actor_session" | "platform_actor_token" | "platform_actor_token_event" | "platform_continued_access" | "platform_outcome_event" | "platform_outsider_consumer" | "platform_saved_view" | "podcast_race" | "processed_document" | "processed_document_page" | "product_capture_file" | "product_capture_item" | "product_capture_payload" | "product_capture_product" | "product_capture_question" | "project" | "provision" | "purpose" | "quiz_session" | "rag_ingest_run" | "redaction_mapping" | "research_analysis" | "research_content" | "research_context_bundle" | "research_document" | "research_keyword" | "research_media" | "research_source" | "research_synthesis" | "research_tag" | "research_template" | "research_topic" | "route_manifest_entry" | "rulebook" | "sandbox_instance" | "sch_agent_task" | "sch_run" | "sch_task" | "sch_trigger" | "scope" | "scope_association_suggestion" | "scope_item_value_suggestion" | "scope_suggestion" | "scope_type" | "seo_ai_visibility_citation" | "seo_ai_visibility_claim" | "seo_ai_visibility_panel" | "seo_ai_visibility_response" | "seo_ai_visibility_signal" | "seo_backlink" | "seo_backlink_change_event" | "seo_backlink_dimension_snapshot" | "seo_backlink_observation" | "seo_backlink_snapshot" | "seo_change_assessment" | "seo_change_event" | "seo_change_item" | "seo_change_metric" | "seo_change_set" | "seo_change_theory" | "seo_collection_run" | "seo_competitor" | "seo_competitor_observation" | "seo_competitor_opportunity" | "seo_coverage_mention" | "seo_coverage_tracker" | "seo_dimension_value_matcher" | "seo_engine_schedule" | "seo_geo_place" | "seo_gsc_dig_rule" | "seo_keyword" | "seo_keyword_class_rule" | "seo_keyword_edge" | "seo_keyword_facet" | "seo_keyword_market" | "seo_keyword_market_observation" | "seo_keyword_place" | "seo_keyword_saved_view" | "seo_keyword_topic" | "seo_landscape_brief" | "seo_link_gap_domain" | "seo_link_gap_match" | "seo_page_measurement_health" | "seo_page_performance" | "seo_provider_call" | "seo_provider_task" | "seo_rank_observation" | "seo_rank_target" | "seo_raw_payload" | "seo_referring_domain_profile" | "seo_reputation_case" | "seo_search_performance_daily" | "seo_serp_mention" | "seo_serp_opportunity" | "seo_serp_result" | "seo_serp_snapshot" | "seo_site_geo_area" | "seo_site_keyword_offering" | "seo_site_keyword_value" | "seo_site_offering_value" | "seo_site_topic_value" | "seo_site_value_combo" | "seo_site_value_worth" | "seo_site_vocabulary" | "seo_source_request" | "seo_starter_pack" | "seo_starter_pack_item" | "seo_story_angle" | "seo_topic" | "seo_web_analytics_daily" | "shared_canvas_item" | "short_link" | "skill" | "skill_render_definition" | "sms_consent" | "sms_conversation" | "sms_message" | "sms_message_media" | "sms_notification" | "sms_notification_preference" | "sms_phone_number" | "structured_list" | "studio_documents" | "studio_recording_chunks" | "studio_recording_segments" | "studio_run" | "studio_session" | "studio_session_settings" | "study_attempt" | "study_goal" | "study_media" | "study_plan" | "study_plan_block" | "study_plan_day" | "study_reminder_context" | "study_reminder_delivery" | "study_session" | "surface" | "system_context_item" | "system_error" | "system_personal_org_failure" | "system_write_failure" | "task" | "thread" | "tool" | "tool_bundle" | "tool_call" | "tool_definition_version" | "tool_test_sample" | "tool_ui" | "tool_ui_incident" | "tool_ui_version" | "transcript" | "udt_dataset_fields" | "udt_dataset_rows" | "udt_document" | "udt_structured_list_items" | "ui_surface_agent_pref" | "ui_surface_config" | "user_achievement" | "user_analysis_preference" | "user_bookmark" | "user_email_preference" | "user_feedback" | "user_form_profile" | "user_markdown_sample" | "user_memory" | "user_preference" | "user_profile" | "user_stat" | "user_surface_state" | "voice" | "war_room" | "wbx_capture" | "wbx_guidance" | "wbx_highlight" | "wbx_pattern" | "wbx_screenshot" | "wbx_seo_audit" | "wc_claim" | "wc_impairment_definition" | "wc_injury" | "wc_report" | "web_analysis_item" | "web_brand" | "web_brand_asset" | "web_brand_offering" | "web_business_fact" | "web_business_location" | "web_crawl_event" | "web_crawl_preset" | "web_crawl_schedule" | "web_crawl_session" | "web_crawl_url" | "web_discovered_item" | "web_finding" | "web_gsc_page_stat" | "web_link_edge" | "web_listing_publisher" | "web_location_listing" | "web_offering_template" | "web_page" | "web_page_content" | "web_page_evidence" | "web_page_sitemap" | "web_property" | "web_provider" | "web_result" | "web_screenshot" | "web_site" | "web_site_endpoint_rule" | "web_site_item_config" | "web_site_offering" | "web_sitemap" | "web_snapshot" | "wf_node_data_slot" | "work_item" | "workbook" | "workflow" | "workflow_card" | "workflow_checkpoint" | "workflow_comparison" | "workflow_definition_version" | "workflow_idempotency" | "workflow_job" | "workflow_node_events" | "workflow_node_outcome" | "workflow_plan" | "workflow_plan_event" | "workflow_plan_sample" | "workflow_recovery_audit" | "workflow_run" | "workflow_run_log" | "workflow_runtime_surface" | "workflow_template" | "workflow_trigger" | "workflow_trigger_fire" | "working_document" | "youtube_search" | "youtube_video";
+
+type AssociationsRpcErrorCode = "unauthorized" | "forbidden_org" | "forbidden_role" | "not_found" | "conflict_in_use" | "invalid_argument" | "version_conflict" | "quota_exceeded"
+/**
+ * THE DEMANDED-SCHEMA SCREAM. A PostgREST missing-function error (PGRST202)
+ * on any demanded RPC maps to this code: the database this client is
+ * pointed at does not run the schema this package demands (README front
+ * door). It always reaches the errorSink — one unambiguous scream, never a
+ * mystery toast. Probe it at boot with `assertDemandedSchema` (/core, W2).
+ */
+ | "demanded_schema_violation" | "internal";
+interface AssociationsRpcError {
+    code: AssociationsRpcErrorCode;
+    message: string;
+    hint?: string;
+    detail?: unknown;
+}
+type AssociationsRpcResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: AssociationsRpcError;
+};
+/**
+ * The structural shape of a PostgREST failure as supabase-js resolves it: a
+ * PLAIN OBJECT parsed from the response body — NOT an `Error` instance.
+ * (Reading `.message` off `instanceof Error` discards the real database
+ * message on every genuine failure; `/core`'s mapper reads these fields.)
+ */
+interface PgError {
+    code?: string | null;
+    message: string;
+    details?: string | null;
+    hint?: string | null;
+}
+
+/**
+ * The minimal table surface entity-row create/rename needs (a structural
+ * subset of supabase-js's query builder). Registry-convention writes go
+ * DIRECT to the backing table (they are RLS-gated feature rows, not
+ * association edges — there is no RPC for them by design).
+ */
+interface AssociationsTableQuery {
+    insert(row: Record<string, unknown>): {
+        select(columns: string): {
+            single(): PromiseLike<{
+                data: unknown;
+                error: PgError | null;
+            }>;
+        };
+    };
+    update(patch: Record<string, unknown>): {
+        eq(column: string, value: string): PromiseLike<{
+            error: PgError | null;
+        }>;
+    };
+}
+/**
+ * The data seam — a structural subset of `SupabaseClient<Database>`: any
+ * client that can answer the demanded RPC families (README § The demanded
+ * schema). The package IS data operations; there is no degraded mode without
+ * one. `PromiseLike` because supabase-js returns a thenable builder, not a
+ * `Promise`.
+ *
+ * `from`/`schema` are OPTIONAL (W2, additive): only the entity-row
+ * create/rename service uses them (generic registry-convention row writes).
+ * A dataSource without them still satisfies every RPC operation; calling
+ * entity-row create/rename against it returns a screamed `{ok:false}`
+ * result naming the missing capability — never a silent no-op. A real
+ * supabase-js client satisfies both structurally.
+ */
+interface AssociationsDataSource {
+    rpc(fn: DemandedRpcName, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: PgError | null;
+    }>;
+    from?(table: string): AssociationsTableQuery;
+    schema?(name: string): {
+        from(table: string): AssociationsTableQuery;
+    };
+}
+/**
+ * The identity seam — today a store-singleton read (`requireUserId`) plus the
+ * org resolver `CategoryTagPicker` uses for created rows. `requireUserId`
+ * failures stay LOUD (`Not authenticated`) — never silently anonymous.
+ */
+interface AssociationsIdentity {
+    requireUserId(): string;
+    /** Org for created rows/edges (the CategoryTagPicker create path). */
+    ensureOrgId?(): Promise<string>;
+}
+/**
+ * The scream seam. Every degraded path, every `demanded_schema_violation`,
+ * every create-then-attach partial failure reports here regardless of
+ * notifier availability.
+ *
+ * DEFAULT (0.6.0, C23): absent → `createDefaultErrorSink()` — a tagged
+ * `console.error` per event that announces ONCE that no sink is bound and
+ * names the remedy. A host with a diagnostics surface binds its own.
+ */
+type ErrorSink = (event: {
+    code: string;
+    message: string;
+    context?: object;
+}) => void;
+/**
+ * Per-token host overlay — the code-native values the DB registry cannot
+ * carry (today: the 804-line ENTITY_OVERLAY literal in matrx-frontend's
+ * entityRegistry). EVERY field optional; absence degrades per field:
+ * convention columns, default icon, `${label}s`, no door, generic
+ * titleColumn candidate read. A `reference_pickable` token with no title
+ * column and no override is screamed to the errorSink, never shown broken.
+ */
+interface EntityOverlayEntry {
+    /** Icon component (host-supplied; packages never depend on an icon library). */
+    Icon?: ElementType;
+    /** Plural label; default `${label}s`. */
+    labelPlural?: string;
+    /** Owner column override; default the "created_by" convention. */
+    ownerColumn?: string | null;
+    /** Org column override; default the "organization_id" convention. */
+    orgColumn?: string | null;
+    /** Route for this token's rows; absent → no open door (label renders plain). */
+    hrefFor?: (id: string) => string;
+    /**
+     * Candidate-list override for tokens whose backing table can't be read
+     * client-side (e.g. `data_store` — rag.* is not PostgREST-exposed);
+     * absent → the generic `reference_search_candidates` titleColumn read.
+     */
+    listCandidates?: (args: {
+        search?: string;
+        limit?: number;
+    }) => Promise<{
+        ok: true;
+        data: {
+            id: string;
+            title: string;
+        }[];
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+/** The overlay registration map — bound per host, merged over the generated registry. */
+type EntityOverlayMap = Partial<Record<EntityTypeToken, EntityOverlayEntry>>;
+/**
+ * The user-notification seam (today: `@/lib/toast` in 6 components).
+ * Optional — /react warns once when absent. Every user-facing failure ALSO
+ * routes to the errorSink + the component's inline error state, so the
+ * create-then-associate loud-outcome law is satisfied structurally, not by
+ * toast availability.
+ */
+interface AssociationsNotifier {
+    success(msg: string): void;
+    error(msg: string, opts?: {
+        description?: string;
+        action?: {
+            label: string;
+            onClick(): void;
+        };
+    }): void;
+}
+/**
+ * The window seam.
+ *
+ * DEFAULT (0.6.0, C23): absent → `DefaultWindowShell`, the package's OWN
+ * window — draggable, resizable, maximizable, viewport-clamped, portalled,
+ * non-modal, mobile bottom-card. Not a degradation; the shipped default.
+ * A host binds this port only when its own window MANAGER (tray docking,
+ * workspace persistence, cross-window z-order) must own the surface.
+ */
+interface WindowShellPort {
+    Window: ComponentType<{
+        id: string;
+        title: string;
+        onClose(): void;
+        children: ReactNode;
+    }>;
+}
+/** Options for {@link CapturePort.requestUpload} (measured: uploadGuardOpeners). */
+interface CaptureUploadOpts {
+    files: File[];
+    /** Logical cloud-files folder new uploads land in (auto-created). */
+    folderPath: string;
+    /** Visibility stamped on uploads (host vocabulary, e.g. "personal"). */
+    visibility?: string;
+}
+/** Honest outcome of a host upload — created-but-unlinked must be reportable. */
+interface CaptureUploadResult {
+    cancelled?: boolean;
+    uploaded: string[];
+    aliased: {
+        existingFileId: string;
+    }[];
+    failed: {
+        name: string;
+        error: string;
+    }[];
+}
+/** Options for {@link CapturePort.openFilePicker} (measured: cloudFilesPickerOpeners). */
+interface CapturePickOpts {
+    multi?: boolean;
+    title?: string;
+    description?: string;
+}
+/**
+ * The capture-toolbar seam. PER-HANDLER optional: the toolbar renders only
+ * the chips it can actually honour; a chip with no path behind it is never
+ * rendered dead. NEVER dead buttons.
+ *
+ * THE UPLOAD DEFAULT (0.6.0, C23): a host does NOT have to build an upload
+ * flow. Bind the one-file primitive `uploadFile` and the package ships the
+ * WHOLE flow over it — the file input, whole-body drag-and-drop, sequential
+ * uploads, the stall watchdog, per-file outcomes, and the loud
+ * created-but-unattached report. `requestUpload` stays for a host that owns
+ * a richer pipeline (duplicate-alias dialogs, progress UI); when both are
+ * bound `requestUpload` wins.
+ */
+interface CapturePort {
+    /**
+     * The MINIMAL upload primitive: persist ONE file, answer with its id (or
+     * an honest error). Everything else — batching, drag-and-drop, progress
+     * state, failure copy — is the package's job.
+     */
+    uploadFile?(file: File, opts: {
+        folderPath: string;
+        visibility?: string;
+    }): Promise<{
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** The full host upload pipeline. Wins over `uploadFile` when bound. */
+    requestUpload?(opts: CaptureUploadOpts): Promise<CaptureUploadResult>;
+    /** Resolves with picked file ids, or null/empty on cancel. */
+    openFilePicker?(opts: CapturePickOpts): Promise<string[] | null>;
+    createDataTable?(opts: {
+        name: string;
+    }): Promise<{
+        id: string;
+    } | null>;
+}
+/**
+ * Props of the generic association picker face — ALSO the contract a
+ * per-token override component must implement (today: the hardcoded
+ * `token === "file"` → FilePickerWindow branch in AssociationPicker becomes a
+ * `registerPickerOverride("file", …)` host binding). Ported verbatim from the
+ * measured component.
+ */
+interface AssociationPickerProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    token: EntityTypeToken;
+    /** Container display label, for the header ("…to Titanium Marketing"). */
+    containerLabel?: string;
+    /** Org stamped onto rows created by the "+ New" footer. */
+    orgId?: string | null;
+    /** Resource ids already attached to the container. */
+    attachedIds: Set<string>;
+    /** Attach a resource (returns ok/err so the row can surface failures). */
+    onAttach: (resourceId: string, title: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Detach a resource. */
+    onDetach: (resourceId: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+}
+/** Per-token picker override map — absent tokens use the generic picker sheet. */
+type PickerOverrideMap = Partial<Record<EntityTypeToken, ComponentType<AssociationPickerProps>>>;
+/**
+ * Props the entity-doors port's `EntityRef` receives (the measured subset the
+ * association faces pass today).
+ */
+interface EntityRefProps {
+    token: string;
+    id: string;
+    name?: string | null;
+    showIcon?: boolean;
+    openInNewTab?: boolean;
+    alwaysShowActions?: boolean;
+    className?: string;
+}
+/** Props the entity-doors port's `DoorControls` receives. */
+interface EntityDoorProps {
+    token: string;
+    id: string;
+    name?: string | null;
+    className?: string;
+}
+/** What the authorDisplay port receives — one comment's denormalized author. */
+interface AuthorDisplayInput {
+    /** The auth user id (`created_by`), or null on an authorless legacy row. */
+    userId: string | null;
+    email: string | null;
+    displayName: string | null;
+    avatarUrl: string | null;
+}
+/**
+ * The author-display seam (W6 comments UI). The package cannot resolve user
+ * profiles itself — `cmt_list` denormalizes email/displayName/avatarUrl per
+ * row, and a host with a richer profile store (presence, current names,
+ * signed avatar URLs) overrides them here. Return `null` (or omit a field)
+ * to keep the denormalized value.
+ *
+ * DEGRADATION (absent port): the RPC's denormalized fields render as-is;
+ * a row with neither displayName nor email shows the package's
+ * "Unknown user" label with the default initial avatar. Never blank, never
+ * a crash.
+ */
+type AuthorDisplayPort = (author: AuthorDisplayInput) => {
+    displayName?: string | null;
+    avatarUrl?: string | null;
+} | null;
+/**
+ * The entity-doors seam (today: `EntityRef` / `EntityDoorControls` /
+ * access-gate `UnresolvedEntityRef`). Absent → title text plus the overlay's
+ * `hrefFor` link when present; unresolved rows render the package's plain
+ * "unavailable" chip.
+ */
+interface EntityDoorsPort {
+    EntityRef?: ComponentType<EntityRefProps>;
+    DoorControls?: ComponentType<EntityDoorProps>;
+    UnresolvedRef?: ComponentType<{
+        token: string;
+        id: string;
+    }>;
+}
+/**
+ * Everything a host binds, once. `createAssociationsStore(cfg)` (/core)
+ * throws when `dataSource` or `identity` is missing — those two ARE the
+ * host's app identity and cannot be defaulted. Every other port ships a
+ * working default (C23) or degrades per its own documented contract, never
+ * silently.
+ */
+interface AssociationsConfig {
+    dataSource: AssociationsDataSource;
+    identity: AssociationsIdentity;
+    errorSink?: ErrorSink;
+    entityOverlay?: EntityOverlayMap;
+    notifier?: AssociationsNotifier;
+    windowShell?: WindowShellPort;
+    capture?: CapturePort;
+    pickerOverrides?: PickerOverrideMap;
+    entityDoors?: EntityDoorsPort;
+    authorDisplay?: AuthorDisplayPort;
+}
+
+declare const ASSOCIATION_TARGET_TYPES: readonly ["organization", "scope", "scope_type", "project", "task", "context_item", "thread", "war_room", "category", "conversation", "fc_set", "fc_card", "study_media", "assessment", "note", "file", "quiz_session", "agent", "research_tag", "skill", "surface", "plan_entity", "plan_node", "web_site", "seo_topic", "seo_keyword", "web_page", "web_screenshot", "party", "crm_outreach_list", "crm_deal", "rulebook"];
+type AssociationTargetType = (typeof ASSOCIATION_TARGET_TYPES)[number];
+interface AssociationEdge {
+    id: string;
+    direction: "outgoing" | "incoming";
+    otherType: string;
+    otherId: string;
+    role: string | null;
+    label: string | null;
+    position: number | null;
+    metadata: unknown;
+    orgId: string | null;
+    createdAt: string;
+}
+interface AssociationTargetEdge {
+    id: string;
+    targetId: string;
+    sourceType: string;
+    sourceId: string;
+    role: string | null;
+    label: string | null;
+    position: number | null;
+    metadata: unknown;
+    orgId: string | null;
+    createdAt: string;
+}
+interface AssociationSourceEdge {
+    id: string;
+    sourceId: string;
+    targetType: string;
+    targetId: string;
+    role: string | null;
+    label: string | null;
+    position: number | null;
+    metadata: unknown;
+    orgId: string | null;
+    createdAt: string;
+}
+interface AssociationsEntry {
+    status: "idle" | "loading" | "ready" | "error";
+    edges: AssociationEdge[];
+    fetchedAt: number | null;
+    error: string | null;
+}
+interface UserEntityState {
+    entityType: string;
+    entityId: string;
+    isFavorite: boolean;
+    isPinned: boolean;
+    isHidden: boolean;
+    lastViewedAt: string | null;
+}
+/** The three boolean dimensions of per-user state, as accepted by `ues_list`. */
+type UserStateKind = "favorite" | "pinned" | "hidden";
+/**
+ * The facet a category belongs to. Open vocabulary (new dimensions need no
+ * migration — `dimension` is free text in the DB); hosts enumerate their
+ * known dimensions as constants.
+ */
+type CategoryDimension = string;
+/** One `platform.categories` row, camelCased (mirrors `cat_list`'s return). */
+interface PlatformCategory {
+    id: string;
+    /** Owning organization; system/global rows use the Matrx System org. */
+    orgId: string | null;
+    dimension: CategoryDimension;
+    name: string;
+    slug: string | null;
+    parentId: string | null;
+    isSystem: boolean;
+    color: string | null;
+    icon: string | null;
+    position: number | null;
+    /**
+     * The row's jsonb metadata — category rows CARRY semantics: e.g. a
+     * `deal_pipeline` stage stores `{outcome: "won"|"lost", probability: 0..100}`
+     * here. Null when empty or when hydrated from an older cache entry.
+     */
+    metadata: Record<string, unknown> | null;
+}
+/** Cache entry for one `dimension` — mirrors `AssociationsEntry`. */
+interface CategoriesEntry {
+    status: "idle" | "loading" | "ready" | "error";
+    categories: PlatformCategory[];
+    fetchedAt: number | null;
+    error: string | null;
+}
+
+/** The author of a comment, denormalized by `cmt_list` from the auth user. */
+interface CommentAuthor {
+    email: string | null;
+    displayName: string | null;
+    avatarUrl: string | null;
+}
+/**
+ * One `platform.comments` row, camelCased (mirrors `cmt_list`'s return).
+ * Threading is by `parentId`: a top-level comment has `parentId === null`;
+ * a reply points at its parent. `cmt_list` returns rows oldest→newest so
+ * callers can build the thread in one pass.
+ */
+interface PlatformComment {
+    id: string;
+    orgId: string | null;
+    entityType: string;
+    entityId: string;
+    parentId: string | null;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+    createdBy: string | null;
+    author: CommentAuthor;
+}
+/**
+ * One cached comment thread (per `${entityType}:${entityId}` endpoint) — the
+ * same lifecycle shape as `AssociationsEntry`/`CategoriesEntry`: pending
+ * keeps previous comments AND the visible error; `fetchedAt` is the last
+ * successful load.
+ */
+interface CommentsEntry {
+    status: "idle" | "loading" | "ready" | "error";
+    comments: readonly PlatformComment[];
+    fetchedAt: number | null;
+    error: string | null;
+}
+
+type ContentRole = "utility" | "source" | "destination" | "hybrid" | "container";
+/**
+ * Fully-resolved entity descriptor — generated metadata + host overlay, with
+ * safe fallbacks so an un-overlaid token still renders (derived plural, no
+ * door, `Icon: null` → the consumer's default) even if it can't be queried
+ * for candidates yet.
+ */
+interface EntityInfo {
+    token: EntityTypeToken;
+    label: string;
+    labelPlural: string;
+    /** Postgres schema of the backing table (from the generated registry). */
+    schema: string;
+    /** Backing table name (from the generated registry). */
+    table: string;
+    /** Title column for the picker, or null when none is registered. */
+    titleColumn: string | null;
+    /** Ownership column to scope candidate reads to the current user. */
+    ownerColumn: string;
+    /** Org-scoping column. */
+    orgColumn: string;
+    /** Host-supplied icon component, or null (consumer renders its default). */
+    Icon: EntityOverlayEntry["Icon"] | null;
+    hrefFor: ((id: string) => string) | null;
+    scopeable: boolean;
+    category: string | null;
+    /** Knowledge-model grouping bucket (resource surfaces group by this). */
+    contentRole: ContentRole;
+    /** Candidate-source override (rag-backed tokens etc.); null = generic read. */
+    listCandidates: EntityOverlayEntry["listCandidates"] | null;
+    /** True when a picker can list real candidates (title column OR override). */
+    canListCandidates: boolean;
+}
+interface EntityRegistry {
+    /** Merge more overlay entries in (host binding, W4 pickers, tests). */
+    registerEntityOverlay(overlay: EntityOverlayMap): void;
+    /** Resolve a KNOWN token to its full descriptor. */
+    getEntityInfo(token: EntityTypeToken): EntityInfo;
+    /** Safe variant for raw strings (e.g. an edge's `otherType`). */
+    tryGetEntityInfo(token: string): EntityInfo | null;
+    /** Resolve from a live `(schema, table)` pair, or null. */
+    tryGetEntityInfoByTable(schema: string, table: string): EntityInfo | null;
+    /** Resolve a raw table name only when it maps to exactly one entity. */
+    tryGetEntityInfoByUniqueTableName(table: string): EntityInfo | null;
+    /**
+     * Tokens the DB classifies as knowledge resources via a valid
+     * `content_role` AND that can list candidates. The default set for card
+     * grids, resource sections, and attach pickers.
+     */
+    curatedTokens(): EntityTypeToken[];
+    /**
+     * Tokens offered as reference "Allowed types" — DB-driven via
+     * `platform.entity_types.reference_pickable`. A pickable token with no
+     * title column and no candidate override is a config defect: excluded and
+     * screamed to the errorSink, never silently shown broken.
+     */
+    listableTokens(): EntityTypeToken[];
+}
+
+interface ConversationFileLink {
+    fileId: string;
+    label: string | null;
+    metadata: unknown;
+    createdAt: string;
+}
+interface AddAssociationArgs {
+    sourceType: string;
+    sourceId: string;
+    targetType: AssociationTargetType;
+    targetId: string;
+    orgId?: string;
+    label?: string;
+    metadata?: unknown;
+    /**
+     * Exact file → conversation updates preserve existing metadata unless the
+     * caller explicitly opts into replacement. Invalid for every other pair.
+     */
+    replaceMetadata?: boolean;
+    role?: string;
+    position?: number;
+    /**
+     * Typed edge payload (Edge Payload System). `payloadKind` must be a
+     * registered `platform.edge_payload_kind`; the DB trigger validates
+     * `payload` against its JSON Schema and hard-fails on any mismatch. Real
+     * logic an edge carries goes HERE — `metadata` is for loose annotations.
+     */
+    payloadKind?: string;
+    payload?: unknown;
+}
+interface AssociationsServiceApi {
+    listForEntity(rawType: string, id: string): Promise<AssociationsRpcResult<{
+        edges: AssociationEdge[];
+    }>>;
+    listConversationFiles(conversationId: string): Promise<AssociationsRpcResult<{
+        files: ConversationFileLink[];
+    }>>;
+    listForTargets(rawTargetType: string, targetIds: string[]): Promise<AssociationsRpcResult<{
+        edges: AssociationTargetEdge[];
+    }>>;
+    listForTargetsVisible(rawTargetType: string, targetIds: string[]): Promise<AssociationsRpcResult<{
+        edges: AssociationTargetEdge[];
+    }>>;
+    listForSources(rawSourceType: string, sourceIds: string[], rawTargetType?: string): Promise<AssociationsRpcResult<{
+        edges: AssociationSourceEdge[];
+    }>>;
+    add(args: AddAssociationArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    remove(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: string;
+        targetId: string;
+        role?: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    setTargets(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    addAgentResource(args: {
+        agentId: string;
+        sourceType: string;
+        sourceId: string;
+        label?: string;
+        metadata?: unknown;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    removeAgentResource(args: {
+        agentId: string;
+        sourceType: string;
+        sourceId: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    removeForEntity(rawType: string, id: string): Promise<AssociationsRpcResult<null>>;
+}
+
+interface CategoriesServiceApi {
+    list(dimension?: CategoryDimension): Promise<AssociationsRpcResult<{
+        categories: PlatformCategory[];
+    }>>;
+    create(args: {
+        dimension: CategoryDimension;
+        name: string;
+        orgId: string;
+        parentId?: string | null;
+        color?: string | null;
+        icon?: string | null;
+        slug?: string | null;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    update(args: {
+        id: string;
+        name: string;
+        slug: string | null;
+        color: string | null;
+        icon: string | null;
+        position: number | null;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    reparent(args: {
+        id: string;
+        parentId: string | null;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    delete(id: string): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+}
+
+interface FavoritesServiceApi {
+    setState(args: {
+        entityType: string;
+        entityId: string;
+        isFavorite?: boolean;
+        isPinned?: boolean;
+        isHidden?: boolean;
+    }): Promise<AssociationsRpcResult<null>>;
+    setFavorite(entityType: string, entityId: string, isFavorite: boolean): Promise<AssociationsRpcResult<null>>;
+    setPinned(entityType: string, entityId: string, isPinned: boolean): Promise<AssociationsRpcResult<null>>;
+    setHidden(entityType: string, entityId: string, isHidden: boolean): Promise<AssociationsRpcResult<null>>;
+    list(kind?: UserStateKind): Promise<AssociationsRpcResult<{
+        items: UserEntityState[];
+    }>>;
+    getBulk(entityType: string, entityIds: string[]): Promise<AssociationsRpcResult<{
+        items: UserEntityState[];
+    }>>;
+    touch(entityType: string, entityId: string): Promise<AssociationsRpcResult<null>>;
+}
+
+interface CandidateRecord {
+    id: string;
+    title: string;
+}
+interface ListCandidatesArgs {
+    token: EntityTypeToken;
+    /** Scope to this owner's rows when the entity declares an owner column. */
+    ownerId?: string | null;
+    /** Case-insensitive title filter. */
+    search?: string;
+    limit?: number;
+}
+type CandidatesResult = {
+    ok: true;
+    data: CandidateRecord[];
+} | {
+    ok: false;
+    error: string;
+};
+interface UniversalCandidate extends CandidateRecord {
+    token: EntityTypeToken;
+}
+interface SearchAcrossTokensArgs {
+    /** Tokens to search. Defaults to every curated token in the registry. */
+    tokens?: EntityTypeToken[];
+    search: string;
+    ownerId?: string | null;
+    /** Cap per token — a universal search shows a few of everything. */
+    perTokenLimit?: number;
+    /** Max in-flight token queries. */
+    concurrency?: number;
+}
+interface ReferenceSearchCandidatesFn {
+    (args: {
+        p_token: string;
+        p_search?: string;
+        p_limit?: number;
+        p_ids?: string[];
+    }): Promise<{
+        data: Array<{
+            id: string;
+            title: string | null;
+        }>;
+        error: null;
+    } | {
+        data: null;
+        error: {
+            message: string;
+        };
+    }>;
+}
+interface CandidatesServiceApi {
+    /**
+     * The universal candidate reader RPC (`public.reference_search_candidates`)
+     * — shared by candidate search here and title resolution in titles.ts.
+     */
+    callReferenceSearchCandidates: ReferenceSearchCandidatesFn;
+    listAssociationCandidates(args: ListCandidatesArgs): Promise<CandidatesResult>;
+    /**
+     * ONE search over EVERY listable entity type — the "attach anything from
+     * anywhere" primitive. Registry-driven client fan-out, capped and
+     * concurrency-limited. Per-token failures are screamed and skipped — one
+     * broken table never blanks the search.
+     */
+    searchCandidatesAcrossTokens(args: SearchAcrossTokensArgs): Promise<UniversalCandidate[]>;
+}
+
+interface TitlesServiceApi {
+    /** Read the cache synchronously (for render paths after a fetch settled). */
+    get(token: string, id: string): string | null;
+    /**
+     * Push a known-fresh title into the cache (after a rename or a create), so
+     * surfaces that resolve through this service never show a stale name.
+     */
+    prime(token: string, id: string, title: string): void;
+    /** Display fallback when no label and no fetched title exist. */
+    fallback(token: string): string;
+    /**
+     * Resolve titles for `ids` of one token. Returns ONLY the resolved entries
+     * (cache + fresh reads); missing rows (deleted, no access) stay absent.
+     */
+    fetch(token: string, ids: string[]): Promise<Map<string, string>>;
+}
+
+type EntityRowResult = {
+    ok: true;
+    data: {
+        id: string;
+        title: string;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+interface CreateEntityRowArgs {
+    /** The new row's human name — written to the registry `titleColumn`. */
+    title: string;
+    /** Org to stamp (skipped when the token has no org column). */
+    orgId?: string | null;
+    /** Required NOT NULL columns the registry conventions can't know about. */
+    extraColumns?: Record<string, unknown>;
+}
+interface EntityRowsServiceApi {
+    createEntityRow(token: EntityTypeToken, args: CreateEntityRowArgs): Promise<EntityRowResult>;
+    renameEntityRow(token: EntityTypeToken, id: string, title: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+
+/** A typed reference to a single row — `{ type, id }`. */
+interface EntityRef {
+    type: EntityTypeToken;
+    id: string;
+}
+/** A container reference — the deliberate set an edge may point at. */
+interface ContainerRef {
+    type: AssociationTargetType;
+    id: string;
+}
+/** Per-edge attributes shared by the link helpers. */
+interface EdgeAttrs {
+    orgId?: string;
+    label?: string;
+    metadata?: unknown;
+    role?: string;
+    position?: number;
+}
+/** One fully-specified edge for {@link AssociationHelpersApi.linkEdges}. */
+interface EdgeSpec extends EdgeAttrs {
+    source: EntityRef;
+    target: ContainerRef;
+}
+interface AssociationHelpersApi {
+    /**
+     * Add an arbitrary batch of edges in one call (idempotent per edge).
+     * Best-effort: every edge is attempted; the result is `ok` with the
+     * created ids only when ALL succeed, otherwise `err` whose `detail` lists
+     * every failure (the edges that DID succeed remain applied — re-running is
+     * safe via ON CONFLICT).
+     */
+    linkEdges(edges: EdgeSpec[]): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /** Attach ONE source to MANY containers in a single shot. */
+    linkOneToMany(args: {
+        source: EntityRef;
+        targets: ContainerRef[];
+        attrs?: EdgeAttrs;
+    }): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /** Attach MANY sources to ONE container in a single shot. */
+    linkManyToOne(args: {
+        sources: EntityRef[];
+        target: ContainerRef;
+        attrs?: EdgeAttrs;
+    }): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /**
+     * REPLACE the full set of a source's edges of one container type (adds
+     * missing, removes extras) in one DB transaction — the set-semantics
+     * one-shot. Thin, named pass-through to `assoc_set_targets`.
+     */
+    replaceTargets(args: {
+        source: EntityRef;
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    /**
+     * Wire edges onto a JUST-CREATED entity. The caller inserts its own row
+     * (entity tables are feature-owned), then passes the new id here to attach
+     * it to any number of containers (orphan-on-partial-fail is harmless and
+     * re-runnable). `created` is the new entity; it becomes the edges' SOURCE.
+     */
+    linkCreated(args: {
+        created: EntityRef;
+        targets: ContainerRef[];
+        attrs?: EdgeAttrs;
+    }): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /** Remove an arbitrary batch of edges (best-effort; no-op per missing edge). */
+    unlinkEdges(edges: {
+        source: EntityRef;
+        target: ContainerRef;
+        role?: string;
+    }[]): Promise<AssociationsRpcResult<null>>;
+}
+
+interface AddCommentArgs {
+    /** Registered entity-type token the comment hangs on (writes-strict, C18). */
+    entityType: string;
+    entityId: string;
+    body: string;
+    /** Reply target — an existing comment's id. Top-level when omitted. */
+    parentId?: string | null;
+    /** Org override; the RPC resolves task-org/personal-org when omitted. */
+    orgId?: string | null;
+}
+interface CommentsServiceApi {
+    listForEntity(entityType: string, entityId: string): Promise<AssociationsRpcResult<{
+        comments: PlatformComment[];
+    }>>;
+    add(args: AddCommentArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    edit(id: string, body: string): Promise<AssociationsRpcResult<null>>;
+    remove(id: string): Promise<AssociationsRpcResult<null>>;
+}
+
+interface AssociationWriteResult {
+    ok: boolean;
+    /** Set on a successful single-edge `add`. */
+    id?: string;
+    error?: string;
+}
+interface CategoryMutationResult {
+    ok: boolean;
+    /** Set on a successful mutation. */
+    id?: string;
+    error?: string;
+}
+interface CommentMutationResult {
+    ok: boolean;
+    /** Set on a successful `addComment`. */
+    id?: string;
+    error?: string;
+}
+interface AssociationsStore {
+    /** Stable, sync read of one endpoint's entry (idle default when uncached). */
+    getEdges(type: string, id: string): AssociationsEntry;
+    /**
+     * Lazy load of every edge touching `${type}:${id}` (both directions).
+     * Deduped per key; `status === "ready"` short-circuits unless `force`.
+     */
+    load(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract: notified whenever the key's entry changes. */
+    subscribe(key: string, cb: () => void): () => void;
+    /** Attach source → target; on success reloads BOTH endpoints. */
+    add(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: AssociationTargetType;
+        targetId: string;
+        orgId?: string;
+        label?: string;
+        role?: string;
+        metadata?: unknown;
+        replaceMetadata?: boolean;
+    }): Promise<AssociationWriteResult>;
+    /** Detach source → target; on success reloads BOTH endpoints. */
+    remove(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: string;
+        targetId: string;
+        role?: string;
+    }): Promise<AssociationWriteResult>;
+    /** Replace the source's `targetType` edge set; reloads the SOURCE. */
+    setTargets(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }): Promise<AssociationWriteResult>;
+    /** Reset one endpoint to idle and notify its subscribers. */
+    invalidate(type: string, id: string): void;
+    /** Reset every association endpoint, category facet, and comment thread. */
+    invalidateAll(): void;
+    getCategories(dimension: CategoryDimension): CategoriesEntry;
+    loadCategories(dimension: CategoryDimension, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    subscribeCategories(dimension: CategoryDimension, cb: () => void): () => void;
+    /** Create + echo-insert + authoritative force reload. Returns the new id. */
+    createCategory(args: {
+        dimension: CategoryDimension;
+        name: string;
+        orgId: string;
+        parentId?: string | null;
+        color?: string | null;
+        icon?: string | null;
+        slug?: string | null;
+    }): Promise<CategoryMutationResult>;
+    updateCategory(args: {
+        dimension: CategoryDimension;
+        id: string;
+        name: string;
+        slug: string | null;
+        color: string | null;
+        icon: string | null;
+        position: number | null;
+    }): Promise<CategoryMutationResult>;
+    reparentCategory(args: {
+        dimension: CategoryDimension;
+        id: string;
+        parentId: string | null;
+    }): Promise<CategoryMutationResult>;
+    deleteCategory(args: {
+        dimension: CategoryDimension;
+        id: string;
+    }): Promise<CategoryMutationResult>;
+    /** Stable, sync read of one entity's comment thread (idle when uncached). */
+    getComments(type: string, id: string): CommentsEntry;
+    /**
+     * Lazy load of every comment on `${type}:${id}` (oldest→newest; thread by
+     * `parentId`). Deduped per key; `status === "ready"` short-circuits unless
+     * `force`.
+     */
+    loadComments(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract for one entity's comment thread. */
+    subscribeComments(key: string, cb: () => void): () => void;
+    /** Post a comment (or a reply); on success force-reloads the thread. */
+    addComment(args: {
+        entityType: string;
+        entityId: string;
+        body: string;
+        parentId?: string | null;
+        orgId?: string | null;
+    }): Promise<CommentMutationResult>;
+    /** Edit a comment body (author-only in the RPC); reloads the thread. */
+    editComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+        body: string;
+    }): Promise<CommentMutationResult>;
+    /** Soft-delete a comment (author/org member in the RPC); reloads the thread. */
+    deleteComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+    }): Promise<CommentMutationResult>;
+    /** Reset one entity's comment thread to idle and notify its subscribers. */
+    invalidateComments(type: string, id: string): void;
+    /** Batched title resolution + the session cache + prime. */
+    titles: TitlesServiceApi;
+    /** Per-user favorite/pinned/hidden state (`ues_*`). */
+    favorites: FavoritesServiceApi;
+    /** Candidate reads for the pickers. */
+    candidates: CandidatesServiceApi;
+    /** Generic registry-convention row create/rename. */
+    entityRows: EntityRowsServiceApi;
+    /** Composite link helpers over the chokepoint. */
+    helpers: AssociationHelpersApi;
+    /** The registry merge engine (generated metadata + host overlay). */
+    registry: EntityRegistry;
+    /**
+     * The raw chokepoint services — every RPC family, results-enveloped.
+     * `associations` writes here do NOT touch the cache; use the store-level
+     * `add`/`remove`/`setTargets` when a cached surface must stay fresh.
+     */
+    services: {
+        associations: AssociationsServiceApi;
+        categories: CategoriesServiceApi;
+        comments: CommentsServiceApi;
+    };
+    /** Merge more host overlay entries in (icons/routes/candidate loaders). */
+    registerEntityOverlay: EntityRegistry["registerEntityOverlay"];
+    /**
+     * The bound scream seam (W3, additive): /react surfaces route their loud
+     * recoveries here (the originals' console.error sites) without a second
+     * sink binding. Same function the host passed at construction.
+     */
+    errorSink: ErrorSink;
+    /**
+     * The bound data seam (0.6.0, additive): the provider's demanded-schema
+     * boot probe reads it so hosts stop re-exporting their dataSource just to
+     * run a check the package owns.
+     */
+    dataSource: AssociationsDataSource;
+    /**
+     * The bound identity port (W3, additive): /react hooks that FILTER by the
+     * current user (candidate owner scoping) read it leniently; write paths
+     * keep going through the services, where `requireUserId` failures stay
+     * loud. Same object the host passed at construction.
+     */
+    identity: AssociationsConfig["identity"];
+}
+
+interface UseAssociationsArgs {
+    /** The entity whose relationships to read/manage (the cache endpoint). */
+    type: string;
+    id: string | null;
+    /** Disable the auto-load on mount. Defaults to false (auto-load). */
+    autoLoad?: boolean;
+}
+
+interface UseAssociationsReturn {
+    /** Every edge touching this entity, both directions. */
+    edges: AssociationEdge[];
+    status: AssociationsEntry["status"];
+    error: string | null;
+    fetchedAt: number | null;
+    /** Attach this entity (as source) → a target. */
+    add: (args: {
+        targetType: AssociationTargetType;
+        targetId: string;
+        orgId?: string;
+        label?: string;
+        /** Typed edge role (e.g. 'theme' for a folder/tag) — omit for a role-less edge. */
+        role?: string;
+    }) => Promise<AssociationWriteResult>;
+    /** Detach this entity (as source) → a target. */
+    remove: (args: {
+        targetType: string;
+        targetId: string;
+        role?: string;
+    }) => Promise<AssociationWriteResult>;
+    /** Replace this entity's edges of one target type with exactly `targetIds`. */
+    setTargets: (args: {
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }) => Promise<AssociationWriteResult>;
+    /** Force a refetch of this entity's edges. */
+    reload: () => Promise<void>;
+}
+declare function useAssociations(args: UseAssociationsArgs): UseAssociationsReturn;
+/**
+ * Convenience alias — same hook, a name that reads naturally on relationship
+ * surfaces ("the things this entity is related to"). Identical contract.
+ */
+declare const useEntityRelationships: typeof useAssociations;
+
+interface ContainerLink {
+    /** The edge id (for keys / removal). */
+    edgeId: string;
+    /** The attached resource's id (the edge source). */
+    resourceId: string;
+    /** The attached resource's entity token (the edge source type). */
+    token: string;
+    /** The edge role, or null for a plain (role-less) association. */
+    role: string | null;
+    label: string | null;
+    /** Per-edge props from `platform.associations.metadata` (e.g. representation). */
+    metadata: unknown;
+}
+interface UseContainerLinksArgs {
+    /** The primary entity — always an association TARGET (container). */
+    containerType: AssociationTargetType;
+    containerId: string | null;
+    /** Org to stamp on new edges (for org-scoped RLS / counts). */
+    orgId?: string | null;
+}
+interface UseContainerLinksReturn {
+    status: ReturnType<typeof useAssociations>["status"];
+    error: string | null;
+    reload: () => Promise<void>;
+    /** Total attached resources across every token (all incoming edges). */
+    totalCount: number;
+    /** Live count of attached resources of `token`. */
+    countFor: (token: EntityTypeToken) => number;
+    /** Ids of resources of `token` already attached (for picker "attached" state). */
+    attachedIdsFor: (token: EntityTypeToken) => Set<string>;
+    /** Full link rows of `token` (for listing/removal). */
+    linksFor: (token: EntityTypeToken) => ContainerLink[];
+    /** Attach a resource (source) to this container (target). */
+    attach: (token: EntityTypeToken, resourceId: string, label?: string, metadata?: unknown, options?: {
+        replaceMetadata?: boolean;
+        /**
+         * Semantic edge role (`platform.associations.role`) — e.g. the
+         * Masterwork dump surface stamps `distillation_source`. Omitted = the
+         * canonical role-less edge. Detach with the SAME role to remove it.
+         */
+        role?: string;
+    }) => Promise<AssociationWriteResult>;
+    /** Detach a resource from this container. */
+    detach: (token: EntityTypeToken, resourceId: string, role?: string) => Promise<AssociationWriteResult>;
+}
+declare function useContainerLinks(args: UseContainerLinksArgs): UseContainerLinksReturn;
+
+interface AssociationEntitySelectItem {
+    id: string;
+    title: string;
+}
+/**
+ * The read/write seam of the association "name dropdown". This hook is the
+ * default (plain associations container); surfaces with bespoke active/create
+ * semantics implement it themselves — same pattern as AssociationList's
+ * ContainerResourcesAdapter.
+ */
+interface AssociationEntitySelectAdapter {
+    /** True while the association list is still hydrating. */
+    loading: boolean;
+    /** Every entity of this token associated with the container. */
+    items: AssociationEntitySelectItem[];
+    activeId: string | null;
+    setActive: (id: string) => void | Promise<unknown>;
+    /**
+     * Create a new entity named `title`, associate it to the container, and
+     * make it active. Resolves to the new id, or null on failure (the adapter
+     * reports its own error detail; the component toasts generically).
+     * Omit when creation isn't name-driven — pass `createSlot` on the component
+     * instead (e.g. a conversation is created by PICKING AN AGENT, not naming).
+     */
+    createAndAttach?: (title: string) => Promise<string | null>;
+    /** Rename the entity (its real title column). Resolves false on failure. */
+    rename: (id: string, title: string) => Promise<boolean>;
+    /** Optional: unlink an entity from the container (never deletes the row). */
+    detach?: (id: string) => Promise<unknown>;
+}
+interface UseAssociationEntitySelectAdapterArgs {
+    token: EntityTypeToken;
+    /** The container the entities are associated with (always the edge TARGET). */
+    container: {
+        type: AssociationTargetType;
+        id: string | null;
+        orgId?: string | null;
+    };
+    /** Controlled active selection; omit to default to the first attached row. */
+    activeId?: string | null;
+    onActiveChange?: (id: string) => void | Promise<unknown>;
+    /** NOT NULL columns the registry conventions can't know (create only). */
+    createColumns?: Record<string, unknown>;
+}
+declare function useAssociationEntitySelectAdapter(args: UseAssociationEntitySelectAdapterArgs): AssociationEntitySelectAdapter;
+
+/** The primary (container) entity a surface is anchored to. */
+interface PrimaryEntity {
+    /** Container token — must be an association TARGET type. */
+    type: AssociationTargetType;
+    id: string;
+    /** Org to stamp on edges created here (org-scoped RLS / counts). */
+    orgId?: string | null;
+    /** Human label for headings (e.g. the org/scope name). */
+    label?: string;
+}
+declare function PrimaryEntityProvider({ value, children, }: {
+    value: PrimaryEntity;
+    children: ReactNode;
+}): react.JSX.Element;
+/** Read the surrounding primary entity, or null when unprovided. */
+declare function usePrimaryEntity(): PrimaryEntity | null;
+
+interface AssociationWindowProps {
+    /** Controls mount — callers should also gate their JSX on this. */
+    open: boolean;
+    onClose: () => void;
+    /** Human-readable scope for the window id (debugging / tray labels). */
+    scopeId: string;
+    title: string;
+    /** Small leading icon rendered beside the title. */
+    icon?: ReactNode;
+    /**
+     * One-line context under the header ("Attached to Titanium Marketing").
+     * A node, not a string, so the container it names can carry its own door
+     * (THE DOOR LAW) instead of being an unreachable label.
+     */
+    subtitle?: ReactNode;
+    children: ReactNode;
+}
+declare function AssociationWindow({ open, onClose, scopeId, title, icon, subtitle, children, }: AssociationWindowProps): react.JSX.Element | null;
+
+interface UniversalAssociationPickerProps {
+    /** Tokens offered. Defaults to every listable token. */
+    tokens?: EntityTypeToken[];
+    /** Ids already attached, keyed `${token}:${id}` — rendered as attached. */
+    attachedKeys: Set<string>;
+    onAttach: (token: EntityTypeToken, resourceId: string, title: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    onDetach: (token: EntityTypeToken, resourceId: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Owner filter for candidate reads (defaults to RLS-only). */
+    ownerId?: string | null;
+    /** Org stamped onto rows created via the per-token "+ New" footer. */
+    orgId?: string | null;
+    className?: string;
+}
+declare function attachedKey(token: string, id: string): string;
+declare function UniversalAssociationPicker(props: UniversalAssociationPickerProps): react.JSX.Element;
+
+interface AttachedItemsSheetProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    token: EntityTypeToken;
+    containerLabel?: string;
+    /**
+     * The container these items are attached to. When given, the "Attached to X"
+     * line puts a door on X — this window can outlive the page it was opened
+     * from, so its container reference must be reachable.
+     */
+    container?: PrimaryEntity;
+    links: ContainerLink[];
+    /** Opens the attach picker. Omitted when the token cannot list candidates. */
+    onAdd?: () => void;
+    onDetach: (resourceId: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+}
+declare function AttachedItemsSheet(props: AttachedItemsSheetProps): react.JSX.Element | null;
+
+interface AssociationCardProps {
+    /** The secondary entity kind this card manages (e.g. "task", "file"). */
+    token: EntityTypeToken;
+    /** Override the page's primary entity. Defaults to PrimaryEntityProvider. */
+    container?: PrimaryEntity;
+    className?: string;
+}
+declare function AssociationCard({ token, container: containerProp, className, }: AssociationCardProps): react.JSX.Element | null;
+
+interface AssociationCardGridProps {
+    /** Tokens to show. Defaults to every registry-listable token. */
+    tokens?: EntityTypeToken[];
+    /** Registry tokens this surface cannot honestly support yet. */
+    excludeTokens?: EntityTypeToken[];
+    className?: string;
+}
+declare function AssociationCardGrid({ tokens, excludeTokens, className, }: AssociationCardGridProps): react.JSX.Element;
+
+/** One attached resource, as the list renders it. Tokens are CANONICAL. */
+interface ContainerResourceRow {
+    /** Stable row key (edge id or `${token}:${id}`). */
+    key: string;
+    token: string;
+    resourceId: string;
+    label: string | null;
+    /** Exact semantic edge role; null means the canonical role-less edge. */
+    role?: string | null;
+    /** Pinned rows sort first inside their token group. */
+    pinned?: boolean;
+    /** False for inherited rows (e.g. via a thread's anchor) — no detach. */
+    removable: boolean;
+    /** Small annotation for non-removable rows ("via anchor"). */
+    originNote?: string | null;
+    /** Resolvable records that contributed an inherited row. */
+    originRefs?: readonly {
+        token: EntityTypeToken;
+        id: string;
+        label: string;
+    }[];
+}
+interface ContainerResourcesAdapter {
+    status: "idle" | "loading" | "ready" | "error";
+    error: string | null;
+    reload: () => void | Promise<void>;
+    rows: ContainerResourceRow[];
+    attach: (token: EntityTypeToken, resourceId: string, title?: string, 
+    /**
+     * Extra edge metadata stamped at attach time (label-at-attach-time's
+     * sibling contract). Adapters without metadata support may ignore it.
+     */
+    opts?: {
+        metadata?: Record<string, unknown> | null;
+    }) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    detach: (token: EntityTypeToken, resourceId: string, role?: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Optional pin capability (edge `metadata.pinned`) — pinned resources stay
+     * inline in agent context at every tier. Rows show a pin toggle when set.
+     */
+    setPinned?: (token: EntityTypeToken, resourceId: string, pinned: boolean) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+}
+/** Default adapter — wraps `useContainerLinks` (org/scope/project pages). */
+declare function useContainerLinksAdapter(container: PrimaryEntity | null, tokens?: readonly EntityTypeToken[]): ContainerResourcesAdapter;
+interface AssociationListProps {
+    /** Container override; defaults to the surrounding PrimaryEntityProvider. */
+    container?: PrimaryEntity;
+    /** Write/read override (war-room threads etc.). Default: useContainerLinks. */
+    adapter?: ContainerResourcesAdapter;
+    /** Restrict display + attach to these tokens (e.g. one dynamic tab). */
+    tokens?: EntityTypeToken[];
+    /** `full` = role sections + universal search; `compact` = flat token groups. */
+    variant?: "full" | "compact";
+    /** Extra per-token actions (e.g. war-room Upload / New document). */
+    renderSectionActions?: (token: EntityTypeToken) => ReactNode;
+    /** Open a resource. Default: registry `hrefFor` in a new tab. */
+    openEntity?: (token: string, id: string) => void;
+    /**
+     * Per-token row override (return null/undefined to keep the default row) —
+     * for rows that need richer rendering than icon+title. The override owns the
+     * whole row; use `ctx` for the resolved title and the busy/detach/open
+     * wiring.
+     */
+    renderRow?: (row: ContainerResourceRow, ctx: {
+        title: string;
+        busy: boolean;
+        onDetach: () => void;
+        onOpen: () => void;
+    }) => ReactNode | null | undefined;
+    className?: string;
+}
+declare function AssociationList(props: AssociationListProps): react.JSX.Element;
+
+type IconProps = SVGProps<SVGSVGElement>;
+/**
+ * The default entity glyph for tokens with no host overlay icon (lucide
+ * `Boxes` — the original registry's DEFAULT_ICON, now a /react concern
+ * because /core ships `Icon: null`).
+ */
+declare function DefaultEntityIcon(props: IconProps): react.JSX.Element;
+
+interface CaptureAttachResult {
+    ok: boolean;
+    /** Human error text — the toolbar screams it. Omit when the host already did. */
+    error?: string;
+}
+/**
+ * ONE write callback for every capture verb. Tokens are canonical
+ * (`file` / `udt_document`); the host maps to its own write path (an
+ * association edge, a thread thunk, …) and reports the outcome honestly —
+ * a silent no-op attach is the bug class this contract kills.
+ */
+type CaptureAttach = (token: EntityTypeToken, resourceId: string, opts?: {
+    label?: string;
+}) => Promise<CaptureAttachResult>;
+interface AssociationCaptureToolbarProps {
+    attach: CaptureAttach;
+    /** Logical cloud-files folder new uploads land in (auto-created). */
+    uploadFolderPath: string;
+    /** Visibility stamped on uploads. Default "personal". */
+    uploadVisibility?: string;
+    /**
+     * Where a created-but-unlinked upload is reported to live, e.g.
+     * "your Files (War Room folder)". Keeps the loud-outcome copy honest.
+     */
+    uploadLocationLabel: string;
+    /** The retry verb named in loud-outcome copy. Default '"Add file"'. */
+    attachRetryLabel?: string;
+    /** Copy for the existing-files picker dialog. */
+    filePicker?: {
+        title?: string;
+        description?: string;
+    };
+    /** Which built-in actions render (each ALSO gated on its port handler). */
+    showActions?: {
+        upload?: boolean;
+        addFile?: boolean;
+        newDocument?: boolean;
+    };
+    /** Hide the button row (compact variants) — drag-and-drop stays live. */
+    showToolbar?: boolean;
+    /** Extra host-specific buttons appended after the built-ins. */
+    extraActions?: ReactNode;
+    /** Open a freshly created document via the registry door. Default true. */
+    openCreatedDocument?: boolean;
+    className?: string;
+    /** The body the drop target wraps (the list of attached things). */
+    children?: ReactNode;
+}
+declare function AssociationCaptureToolbar({ attach, uploadFolderPath, uploadVisibility, uploadLocationLabel, attachRetryLabel, filePicker, showActions, showToolbar, extraActions, openCreatedDocument, className, children, }: AssociationCaptureToolbarProps): react.JSX.Element;
+/** The dense toolbar button (exported so hosts' extraActions match). */
+declare function CaptureToolbarAction({ icon: Icon, label, onClick, disabled, spinning, }: {
+    icon: (props: IconProps) => ReactNode;
+    label: string;
+    onClick: () => void;
+    disabled?: boolean;
+    spinning?: boolean;
+}): react.JSX.Element;
+
+interface AssociationEntitySelectProps {
+    token: EntityTypeToken;
+    adapter: AssociationEntitySelectAdapter;
+    className?: string;
+    /** Label sizing/typography override (defaults to toolbar-dense text-xs). */
+    labelClassName?: string;
+    align?: "start" | "end";
+    showIcon?: boolean;
+    /** How the name enters inline edit. Default "click". */
+    renameActivation?: "click" | "doubleClick";
+    /** Shown while no entity is active yet. Defaults to the plural label. */
+    emptyLabel?: string;
+    /** Icon color accent (e.g. "text-yellow-500" for notes). */
+    iconClassName?: string;
+    /**
+     * Replaces the default "+ New <Entity>" name-input footer with a custom
+     * creator (e.g. an agent picker that starts a new chat). Function form
+     * receives `close` so the creator can dismiss the dropdown when done.
+     */
+    createSlot?: React.ReactNode | ((close: () => void) => React.ReactNode);
+}
+declare function AssociationEntitySelect({ token, adapter, className, labelClassName, align, showIcon, renameActivation, emptyLabel, iconClassName, createSlot, }: AssociationEntitySelectProps): react.JSX.Element;
+
+interface CategorySelectProps {
+    dimension: CategoryDimension;
+    value: string | null;
+    onChange: (id: string | null) => void;
+    placeholder: string;
+    allowNone?: boolean;
+    disabled?: boolean;
+    /**
+     * Offer "Create «what you typed»". On by default — a closed category list is
+     * a defect, so turning this off needs a reason a person would accept.
+     */
+    allowCreate?: boolean;
+    /**
+     * Org for an inline-created category. Defaults to the identity port's
+     * `ensureOrgId()`; with neither, create refuses loudly.
+     */
+    orgId?: string | null;
+    /** What one of these is called, for the create affordance ("stage", "folder"). */
+    noun?: string;
+}
+declare function CategorySelect({ dimension, value, onChange, placeholder, allowNone, disabled, allowCreate, orgId, noun, }: CategorySelectProps): react.JSX.Element;
+
+/** Structural stand-in for the host's `LucideIcon` on the `icon` prop. */
+type TagPickerIcon = ComponentType<{
+    className?: string;
+}>;
+interface CategoryTagPickerProps {
+    /** The tagged entity's registered association type (e.g. "fc_set", "party"). */
+    entityType: string;
+    entityId: string;
+    /** The `platform.categories` facet the picker offers. */
+    dimension: CategoryDimension;
+    /** The typed edge role the assignment edges carry (e.g. "theme", "member"). */
+    edgeRole: string;
+    /**
+     * Org for the edge write and for inline-created categories. Defaults to the
+     * identity port's `ensureOrgId()` (create only) — pass the owning entity's
+     * org when it has one.
+     */
+    orgId?: string | null;
+    /** Trigger label while nothing is selected. */
+    addLabel?: string;
+    /** Trigger icon. */
+    icon?: TagPickerIcon;
+    /** Offer "Create <term>" for unmatched search terms. Default true. */
+    allowCreate?: boolean;
+    /**
+     * Force the two-level face on or off. Omit to detect it from parentId rows,
+     * which leaves every existing flat facet visually unchanged.
+     */
+    hierarchical?: boolean;
+    emptyText?: string;
+}
+/**
+ * Multi-select combobox: badges for the entity's current tags in `dimension`,
+ * a popover to toggle existing categories, optional inline create. Fully
+ * self-contained — mount it once per entity and it reads/writes the edges.
+ */
+declare function CategoryTagPicker({ entityType, entityId, dimension, edgeRole, orgId, addLabel, icon: Icon, allowCreate, hierarchical, emptyText, }: CategoryTagPickerProps): react.JSX.Element;
+
+interface CommentThreadProps {
+    /** Entity-type token of the commented-on entity. */
+    token: EntityTypeToken;
+    /** The entity's row id. */
+    id: string;
+    /** Org override forwarded to `cmt_add` (the RPC resolves one when omitted). */
+    orgId?: string | null;
+    /** Hide the slim "Comments · n" header row. Defaults to shown. */
+    showHeader?: boolean;
+    className?: string;
+}
+interface CommentComposerProps {
+    /** Post the body; resolve `{ok:false}` to keep the text + show the error. */
+    onSubmit: (body: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    placeholder?: string;
+    submitLabel?: string;
+    /** Initial body (the edit flow seeds the current text). */
+    initialValue?: string;
+    /** Rendered right of the submit button (the Cancel affordance). */
+    trailing?: ReactNode;
+    autoFocus?: boolean;
+}
+/**
+ * The one composer every comment write goes through (new comment, reply,
+ * edit). Submit on the button or Cmd/Ctrl+Enter; the text survives a failed
+ * submit alongside the inline error (input is never lost).
+ */
+declare function CommentComposer({ onSubmit, placeholder, submitLabel, initialValue, trailing, autoFocus, }: CommentComposerProps): react.JSX.Element;
+/**
+ * Build the parent→children index. A reply whose parent is missing from the
+ * list (soft-deleted parent, partial page) is promoted to top level rather
+ * than dropped — every visible comment stays reachable.
+ */
+declare function buildCommentTree(comments: readonly PlatformComment[]): {
+    roots: PlatformComment[];
+    childrenOf: Map<string, PlatformComment[]>;
+};
+declare function CommentThread({ token, id, orgId, showHeader, className, }: CommentThreadProps): react.JSX.Element;
+
+export { DefaultEntityIcon as $, type AssociationCaptureToolbarProps as A, AssociationCaptureToolbar as B, type CategorySelectProps as C, AssociationCard as D, type EntityDoorsPort as E, AssociationCardGrid as F, AssociationEntitySelect as G, type AssociationEntitySelectAdapter as H, type AssociationEntitySelectItem as I, AssociationList as J, AssociationWindow as K, type AssociationWriteResult as L, AttachedItemsSheet as M, type CaptureAttach as N, type CaptureAttachResult as O, type PickerOverrideMap as P, CaptureToolbarAction as Q, CategorySelect as R, CategoryTagPicker as S, CommentComposer as T, type UniversalAssociationPickerProps as U, type CommentComposerProps as V, type WindowShellPort as W, CommentThread as X, type ContainerLink as Y, type ContainerResourceRow as Z, type ContainerResourcesAdapter as _, type AssociationCardProps as a, type PrimaryEntity as a0, PrimaryEntityProvider as a1, type TagPickerIcon as a2, UniversalAssociationPicker as a3, type UseAssociationEntitySelectAdapterArgs as a4, type UseAssociationsArgs as a5, type UseAssociationsReturn as a6, type UseContainerLinksArgs as a7, type UseContainerLinksReturn as a8, attachedKey as a9, buildCommentTree as aa, useAssociationEntitySelectAdapter as ab, useAssociations as ac, useContainerLinks as ad, useContainerLinksAdapter as ae, useEntityRelationships as af, usePrimaryEntity as ag, type AssociationCardGridProps as b, type AssociationEntitySelectProps as c, type AssociationListProps as d, type AssociationPickerProps as e, type AssociationWindowProps as f, type AttachedItemsSheetProps as g, type CategoryTagPickerProps as h, type CommentThreadProps as i, type AssociationsNotifier as j, type CapturePort as k, type AuthorDisplayPort as l, type AssociationsStore as m, type CategoryMutationResult as n, type CategoryDimension as o, type PlatformCategory as p, type CategoriesEntry as q, type EntityTypeToken as r, type UniversalCandidate as s, type CandidateRecord as t, type PlatformComment as u, type CommentsEntry as v, type CommentMutationResult as w, type EntityDoorProps as x, type EntityRefProps as y, type ContentRole as z };