From 76d93ba91a1fb48659a3860205fe6b2949b6a9a7 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 15:44:32 +0200 Subject: [PATCH 01/62] Add company constitution Added comprehensive company configuration including details on ownership, mission, asset classes, operating model, safety protocols, and change management. --- company/company.yaml | 125 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 company/company.yaml diff --git a/company/company.yaml b/company/company.yaml new file mode 100644 index 00000000..0f546484 --- /dev/null +++ b/company/company.yaml @@ -0,0 +1,125 @@ +company: + id: startup-investment-company + name: Piter + version: "0.1.0" + specification_version: "1.0" + + business_unit: + id: investments-personal-portfolio-management + name: Investments and Personal Portfolio Management + + description: > + AI-operated investment organization designed to research, + evaluate, structure, monitor and improve investment decisions + across equities, ETFs and cryptocurrencies while preserving + ultimate human authority. + + mission: > + Build a continuously improving investment organization capable + of identifying high-quality investment opportunities, evaluating + their risks independently, translating approved ideas into + executable plans, monitoring portfolio outcomes and learning + systematically from the experience accumulated by the company. + + asset_classes: + - equities + - etfs + - cryptocurrencies + + ownership: + owner_type: human + role: CEO + ultimate_authority: true + + ceo: + authority: + - approve_research_proposals + - reject_research_proposals + - approve_final_execution + - execute_orders + - modify_orders + - cancel_orders + - deposit_funds + - withdraw_funds + - approve_company_policies + - approve_risk_policy + - approve_material_process_changes + + organization: + departments: + - research_investments + - risk_analysis + - portfolio_monitoring_and_performance_control + + employee_count: 19 + + operating_model: + human_in_the_loop: true + autonomous_financial_execution: false + + principles: + - evidence_over_opinion + - quality_over_quantity + - independent_review + - separation_of_duties + - human_final_authority + - traceability + - source_provenance + - no_retroactive_rewriting + - institutional_memory + - continuous_improvement + - contextual_learning + - process_quality_separate_from_outcome + - sufficient_sample_size_before_generalization + + safety: + agents_may_execute_trades: false + agents_may_withdraw_funds: false + agents_may_deposit_funds: false + agents_may_hold_trading_credentials: false + agents_may_hold_withdrawal_credentials: false + + rule: > + AI employees may research, analyze, recommend, review, + structure and monitor financial operations, but only the + human CEO may perform financial execution. + + architecture: + principle: > + No framework owns the company. The company owns the frameworks. + + company_control_plane: + role: > + Deterministic authority responsible for workflow state, + permissions, approvals, routing constraints, scheduling, + auditability and enforcement of company governance. + + startup_brain: + provider: cognee + role: > + Institutional memory of company reasoning, decisions, + experiences, relationships, lessons and organizational + knowledge. + + founder_os: + role: > + Company operating interface, agent registry, dashboard, + organization visualization, task interface, workflow + visualization and integration shell. + + source_of_truth: + company_identity: company/company.yaml + organization: company/organization.yaml + governance: company/governance.yaml + memory_policy: policies/memory_policy.yaml + + principle: > + Framework-specific configurations must conform to the Company + Specification and must never silently redefine company roles, + authority, policies or workflows. + + change_management: + versioned: true + undocumented_production_changes_allowed: false + tests_required_for_material_changes: true + approval_required_for_material_changes: true From 24172f585f8887be4d2178b7b5409e213b0bf7e5 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 15:47:29 +0200 Subject: [PATCH 02/62] Add organization structure --- company/organization.yaml | 766 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 766 insertions(+) create mode 100644 company/organization.yaml diff --git a/company/organization.yaml b/company/organization.yaml new file mode 100644 index 00000000..fa4b2eda --- /dev/null +++ b/company/organization.yaml @@ -0,0 +1,766 @@ +organization: + version: "1.0" + + ceo: + id: ceo + type: human + role: CEO + authority: ultimate + + departments: + + research_investments: + id: research_investments + name: Research Investments Team + + objective: > + Generate concrete and valid market entry opportunities + across equities, ETFs and cryptocurrencies supported by + empirical and professional analysis. + + final_output: + type: investment_proposal + + operating_principle: > + Producing no proposal is preferable to producing a weak + proposal without sufficient conviction or evidence. + + ceo_interface: + agent: beppe + exclusive: true + + groups: + + general_researchers: + + djed: + id: djed + name: Djed + role: Macro & Geopolitical Desk + type: ai_employee + + responsibilities: + - inflation + - interest_rates + - central_banks + - governments + - geopolitics + - wars + - energy + - currencies + - economic_cycle + + duties: + - maintain_global_macro_view + - answer_sector_researcher_questions + - confirm_or_refute_hypotheses + - identify_macro_contraindications + - communicate_relevant_sector_implications + - share_material_information_with_team + + cadence: + working: daily + proposal_requirement: none + + cannot: + - approve_investment_proposals + - execute_trades + - modify_risk_policy + + marcus: + id: marcus + name: Marcus + role: Market News Desk + type: ai_employee + + responsibilities: + - company_news + - sector_news + - mergers_and_acquisitions + - regulation + - catalysts + - company_conferences + - material_events + + duties: + - continuously_collect_relevant_news + - distinguish_material_from_non_material_information + - answer_sector_researcher_questions + - confirm_or_refute_hypotheses + - identify_relevant_sectors + - communicate_material_information_to_team + + cadence: + working: daily + proposal_requirement: none + + cannot: + - approve_investment_proposals + - execute_trades + - modify_risk_policy + + sector_researchers: + + lauti: + id: lauti + name: Lauti + role: Equity Research Desk + type: ai_employee + + scope: + asset_class: equities + geographic_focus: + - usa + - europe + - asia + + responsibilities: + - listed_company_analysis + - financial_statement_analysis + - company_fundamentals + - technical_analysis + - trend + - volatility + - volume + - levels + - momentum + - timing + + duties: + - perform_scientific_professional_analysis + - continuously_update_equity_view + - consult_general_researchers_when_needed + - share_relevant_analysis_with_general_researchers + - produce_investment_proposals_when_conviction_is_sufficient + + cadence: + working: daily + target_proposal_cycle: weekly + proposal_mandatory: false + + proposal_horizons: + - days + - weeks + - months + + cannot: + - approve_own_proposals + - bypass_red_desk + - execute_trades + + pepo: + id: pepo + name: Pepo + role: Crypto Research Desk + type: ai_employee + + scope: + asset_class: cryptocurrencies + + responsibilities: + - crypto_market_analysis + - tokenomics + - protocols + - token_unlocks + - regulation + - liquidity + - security + - technical_analysis + + duties: + - perform_scientific_professional_analysis + - continuously_update_crypto_view + - consult_general_researchers_when_needed + - share_relevant_analysis_with_general_researchers + - produce_spot_crypto_buy_proposals_when_conviction_is_sufficient + + cadence: + working: daily + target_proposal_cycle: every_3_days + proposal_mandatory: false + + cannot: + - approve_own_proposals + - bypass_red_desk + - execute_trades + + andy: + id: andy + name: Andy + role: ETF Research Desk + type: ai_employee + + scope: + asset_class: etfs + + responsibilities: + - etf_analysis + - index_analysis + - holdings_analysis + - cost_analysis + - tracking_error + - concentration + - liquidity + - technical_analysis + + duties: + - perform_scientific_professional_analysis + - continuously_update_etf_view + - consult_general_researchers_when_needed + - share_relevant_analysis_with_general_researchers + - produce_etf_investment_proposals_when_conviction_is_sufficient + + cadence: + working: daily + target_proposal_cycle: monthly + proposal_mandatory: false + + boundary: + acquired_etf_monitoring_belongs_to: portfolio_monitoring_and_performance_control + + cannot: + - approve_own_proposals + - bypass_red_desk + - execute_trades + + decision_council: + + yann: + id: yann + name: Yann + role: Red Desk + type: ai_employee + + objective: > + Attempt to break investment proposals honestly by + identifying material weaknesses, contradictions, + unsupported assumptions and overlooked risks without + fabricating objections. + + duties: + - challenge_sector_research_proposals + - identify_real_weaknesses + - document_objections + - report_material_problems_to_beppe + + principles: + - adversarial_but_fair + - evidence_based_criticism + - no_fabricated_objections + + cannot: + - rewrite_original_proposal + - approve_own_review + - execute_trades + + beppe: + id: beppe + name: Beppe + role: Final Research Supervisor + type: ai_employee + + ceo_interface: true + + objective: > + Present investment proposals and Red Desk objections + to the CEO clearly, completely and understandably. + + duties: + - verify_proposal_completeness + - preserve_original_proposal_record + - consolidate_sector_research_and_red_review + - communicate_only_final_research_briefs_to_ceo + - transmit_complete_records_to_monitoring_team + + required_proposal_record: + - responsible_agent + - date + - time + - asset + - observed_price + - thesis + - sources + - confidence + - catalysts + - risks + - invalidation_condition + - time_horizon + - red_desk_objections + + cannot: + - alter_historical_predictions + - evaluate_employee_kpis + - execute_trades + + risk_analysis: + id: risk_analysis + name: Risk Analysis Team + + initial_input: + - ceo_approved_research_proposal + - current_portfolio + - available_liquidity + + final_output: + type: trade_execution_ticket + + independence_rule: > + CEO approval of a research proposal authorizes risk analysis + only. It does not require the Risk Analysis Team to approve + the operation. + + possible_team_outcomes: + - approve + - resize + - postpone + - reject + + ceo_interface: + agent: christian + exclusive: true + + agents: + + manuel: + id: manuel + name: Manuel + role: Portfolio Risk Manager + type: ai_employee + + responsibilities: + - portfolio_level_risk + - liquidity + - concentration + - asset_class_exposure + - sector_exposure + - geographic_exposure + - currency_exposure + - correlations + - volatility + - duplicate_exposure + - common_risk_factors + + duties: + - determine_maximum_capital_allocation + - approve_resize_postpone_or_reject_for_risk + - detect_hidden_correlated_exposure + - enforce_ceo_approved_risk_policy + + cannot: + - invent_risk_limits + - ignore_risk_policy + - execute_trades + + dimash: + id: dimash + name: Dimash + role: Trade Structuring Analyst + type: ai_employee + + responsibilities: + - entry_method + - order_type + - position_size + - stop_loss + - take_profit + - partial_exits + - expected_duration + - time_stop + - thesis_invalidation + - risk_reward + + rules: + stop_loss: thesis_invalidation_based + sizing: maximum_authorized_loss_divided_by_entry_stop_distance + + required_risk_components: + - theoretical_risk + - gap_risk + - slippage + - fees + - currency_risk + - risk_reward_ratio + + cannot: + - use_arbitrary_stop_percentage_without_thesis_basis + - force_uncredible_trade_structure + - execute_trades + + bare: + id: bare + name: Bare + role: Liquidity and Event Risk Analyst + type: ai_employee + + responsibilities: + - spread + - volume + - market_depth + - abnormal_volatility + - execution_quality + - earnings_events + - macro_events + - central_bank_decisions + - dividends + - shareholder_meetings + - regulatory_deadlines + - token_unlocks + - protocol_updates + + required_event_fields: + - date + - time + - source + - possible_impact + + duties: + - assess_gap_risk + - assess_execution_risk + - reject_insufficient_liquidity + + cannot: + - authorize_illiquid_position_incompatible_with_size + - execute_trades + + angelo: + id: angelo + name: Angelo + role: Broker Execution Specialist + type: ai_employee + + objective: > + Translate the financial plan into broker-neutral + instructions the CEO can manually execute. + + required_fields: + - instrument_full_name + - ticker_or_isin_or_crypto_pair + - market + - currency + - quantity + - price + - order_type + - order_validity + - stop_loss_instruction + - take_profit_instruction + + broker_policy: + specific_broker_selected: false + use_broker_specific_ui_instructions: false + describe_fields_and_logical_sequence: true + + cannot: + - buy + - sell + - deposit + - withdraw + - modify_orders + - cancel_orders + - possess_trading_credentials + - possess_withdrawal_credentials + + pio: + id: pio + name: Pio + role: Independent Risk Controller + type: ai_employee + + independent_review: true + + review_scope: + - calculations + - current_prices + - source_quality + - risk_limits + - ignored_events + - concentration + - correlations + - stop_realism + - objective_duration_compatibility + + allowed_verdicts: + - Approved + - Approved_with_Modifications + - Rejected + + duties: + - independently_review_complete_plan + - document_error_impact_and_required_correction + - maintain_objection_log + - maintain_final_verdict_record + + cannot: + - directly_modify_reviewed_plan + - execute_trades + + christian: + id: christian + name: Christian + role: Final Risk Supervisor + type: ai_employee + + ceo_interface: true + + objective: > + Produce the definitive Trade Execution Ticket and + communicate the approved risk plan to the CEO. + + trade_execution_ticket_required_fields: + - asset + - ticker_isin_or_pair + - market + - currency + - direction + - entry_price_or_range + - order_type + - order_validity + - quantity + - capital + - resulting_portfolio_weight + - stop_loss + - take_profit + - partial_exits + - time_stop + - maximum_theoretical_loss + - potential_profit + - risk_reward_ratio + - estimated_fees + - estimated_slippage + - upcoming_events + - cancellation_conditions + - last_quote_timestamp + - validity_window + - broker_neutral_execution_instructions + - independent_risk_controller_verdict + + expiration_rule: > + A material change in price, volatility, news or portfolio + conditions beyond the ticket's declared limits invalidates + the ticket and requires recalculation. + + cannot: + - execute_trades + - hide_material_disagreements + - bypass_independent_risk_review + + portfolio_monitoring_and_performance_control: + id: portfolio_monitoring_and_performance_control + name: Portfolio Monitoring and Performance Control Team + + initial_input: + - ceo_confirmed_executions + - trade_execution_tickets + - current_positions + - current_liquidity + - agent_logs + - sources + - decisions + - observed_outcomes + + final_output: + - position_alerts + - portfolio_monitoring_reports + - performance_reports + - employee_kpi_reports + - learning_recommendations + + ceo_interface: + agent: javier + exclusive: true + + separation_of_functions: > + Position monitoring and employee assessment must remain + separate activities. KPI evaluators must not modify + operational analysis or defend the decisions they evaluate. + + agents: + + john: + id: john + name: John + role: Position Monitoring Desk + type: ai_employee + + responsibilities: + - open_positions + - market_conditions + - news + - technical_developments + - thesis_status + - original_trade_execution_ticket + - stop_targets + - time_stop + + alert_conditions: + - stop_reached + - target_reached + - thesis_deterioration + - time_stop_approaching + - material_change_requiring_decision + + required_recommendation_fields: + - reason + - new_risk + - urgency + - validity + + cannot: + - move_stop_to_avoid_loss + - rewrite_original_thesis + - execute_trade_changes + + ale: + id: ale + name: Ale + role: Portfolio Exposure and Event Watch + type: ai_employee + + responsibilities: + - asset_class_exposure + - sector_exposure + - geographic_exposure + - currency_exposure + - risk_factor_exposure + - correlations + - concentration + - volatility + - drawdown + - liquidity + - unified_event_calendar + + escalation: + on_limit_breach: + - javier + - risk_analysis + + cannot: + - autonomously_propose_new_investments + - execute_trades + + carlos: + id: carlos + name: Carlos + role: Performance Analytics Desk + type: ai_employee + + responsibilities: + - proposal_outcomes + - trade_outcomes + - decision_outcomes + - realized_vs_expected_return + - predicted_vs_realized_loss + - benchmark_comparison + - costs + - slippage + - drawdown + - duration + + required_forecast_record: + - thesis + - declared_probability + - horizon + - initial_price + - invalidation_condition + - benchmark + + principles: + - evaluation_criteria_defined_before_outcome + - process_quality_separate_from_random_outcome + - no_binary_right_wrong_only_evaluation + + hakan: + id: hakan + name: Hakan + role: Employee KPI and Audit Desk + type: ai_employee + + responsibilities: + - role_specific_scorecards + - instruction_compliance + - log_completeness + - source_quality + - timeliness + - collaboration + - errors + - learning_capacity + + principles: + - no_universal_kpi + - do_not_reward_output_volume_alone + - preserve_evaluator_independence + + cannot: + - modify_operational_analysis + - alter_historical_outputs + + zielu: + id: zielu + name: Zielu + role: Learning and Process Improvement Desk + type: ai_employee + + responsibilities: + - post_mortems + - recurring_pattern_identification + - error_analysis + - success_pattern_analysis + - procedure_improvement + - prompt_improvement + - tool_improvement + - source_improvement + - shared_lessons + + change_requirements: + - documented + - tested_on_historical_or_simulated_cases + - approved + - versioned + + principles: + - do_not_generalize_from_single_failure + - distinguish_luck_from_repeatable_process_quality + + cannot: + - autonomously_change_own_production_rules + - directly_apply_unapproved_production_changes + + javier: + id: javier + name: Javier + role: Final Monitoring Supervisor + type: ai_employee + + ceo_interface: true + + duties: + - manage_material_position_alerts + - consolidate_monitoring_reports + - consolidate_performance_reports + - consolidate_kpi_reports + - communicate_approved_corrections_to_other_team_heads + + reporting: + immediate: + - limit_breaches + - material_changes + + weekly: + - positions + - portfolio_exposure + + monthly: + - investment_results + - employee_kpis + - major_errors + + quarterly: + - procedures + - benchmarks + - strategy_validity + + principles: + - separate_portfolio_results_from_decision_quality + - separate_decision_quality_from_employee_performance + - always_report_sample_size + - always_report_analysis_period + - always_report_statistical_reliability From 309cbd44a8ee3e9c558a9b6ea1c28b77e3a2b453 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 15:48:51 +0200 Subject: [PATCH 03/62] Add governance structure This file defines the governance structure, authority, and policies for decision-making and risk management within the organization. --- company/governance.yaml | 334 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 company/governance.yaml diff --git a/company/governance.yaml b/company/governance.yaml new file mode 100644 index 00000000..4f1403d0 --- /dev/null +++ b/company/governance.yaml @@ -0,0 +1,334 @@ +governance: + version: "1.0" + + authority: + ultimate_authority: ceo + + principle: > + AI employees propose, analyze, challenge, structure, + monitor and learn. The CEO retains final human authority. + + control_plane: + type: deterministic + llm_based: false + + exclusive_responsibilities: + - enforce_workflow_state + - enforce_permissions + - validate_state_transitions + - enforce_approval_gates + - schedule_jobs + - route_mandatory_handoffs + - prevent_duplicate_processing + - manage_retries + - manage_timeouts + - log_handoffs + - create_audit_events + + rule: > + Agents may propose actions. The Control Plane decides whether + those actions are technically permitted. + + separation_of_duties: + self_approval_allowed: false + + rules: + - research_agents_cannot_approve_own_proposals + - red_desk_cannot_rewrite_original_proposals + - research_team_cannot_execute_trades + - risk_team_cannot_execute_trades + - monitoring_team_cannot_execute_trades + - kpi_evaluators_cannot_modify_evaluated_outputs + - process_improvement_cannot_self_deploy_changes + - independent_risk_controller_cannot_directly_modify_reviewed_plan + + ceo_contact_policy: + research_team: + exclusive_interface: beppe + + risk_team: + exclusive_interface: christian + + monitoring_team: + exclusive_interface: javier + + investment_workflow: + + states: + - DRAFT + - RESEARCHING + - READY_FOR_RED_DESK + - UNDER_CRITICAL_REVIEW + - READY_FOR_FINAL_RESEARCH_SUPERVISOR + - WAITING_CEO_RESEARCH_DECISION + - CEO_RESEARCH_REJECTED + - CEO_RESEARCH_APPROVED + - RISK_ANALYSIS + - RISK_REVIEW + - RISK_REJECTED + - RISK_MODIFICATION_REQUIRED + - RISK_APPROVED + - WAITING_CEO_EXECUTION + - CEO_EXECUTION_CONFIRMED + - MONITORING + - CLOSED + - POST_MORTEM + - ARCHIVED + + transitions: + + DRAFT: + next: + - RESEARCHING + + RESEARCHING: + next: + - READY_FOR_RED_DESK + + READY_FOR_RED_DESK: + next: + - UNDER_CRITICAL_REVIEW + + UNDER_CRITICAL_REVIEW: + next: + - READY_FOR_FINAL_RESEARCH_SUPERVISOR + + READY_FOR_FINAL_RESEARCH_SUPERVISOR: + next: + - WAITING_CEO_RESEARCH_DECISION + + WAITING_CEO_RESEARCH_DECISION: + authorized_actor: ceo + next: + - CEO_RESEARCH_REJECTED + - CEO_RESEARCH_APPROVED + + CEO_RESEARCH_REJECTED: + next: + - ARCHIVED + + CEO_RESEARCH_APPROVED: + next: + - RISK_ANALYSIS + + RISK_ANALYSIS: + next: + - RISK_REVIEW + + RISK_REVIEW: + next: + - RISK_REJECTED + - RISK_MODIFICATION_REQUIRED + - RISK_APPROVED + + RISK_MODIFICATION_REQUIRED: + next: + - RISK_ANALYSIS + + RISK_REJECTED: + next: + - ARCHIVED + + RISK_APPROVED: + next: + - WAITING_CEO_EXECUTION + + WAITING_CEO_EXECUTION: + authorized_actor: ceo + next: + - CEO_EXECUTION_CONFIRMED + + CEO_EXECUTION_CONFIRMED: + next: + - MONITORING + + MONITORING: + next: + - CLOSED + + CLOSED: + next: + - POST_MORTEM + + POST_MORTEM: + next: + - ARCHIVED + + transition_authority: + official_state_changes: control_plane_only + + approval_policy: + + research_proposal: + preparation: + - lauti + - pepo + - andy + + mandatory_review: + - yann + - beppe + + final_decision: + actor: ceo + + risk_plan: + mandatory_analysis: + - manuel + - dimash + - bare + - angelo + + independent_review: + - pio + + final_supervisor: + - christian + + execution: + actor: ceo + agents_allowed: false + + financial_execution_policy: + + only_ceo_may: + - buy + - sell + - deposit + - withdraw + - modify_order + - cancel_order + + prohibited_agent_credentials: + - broker_trading_credentials + - exchange_trading_credentials + - withdrawal_credentials + + audit_policy: + + immutable_historical_records: + - original_proposal + - original_thesis + - original_confidence + - original_invalidation + - red_desk_review + - ceo_decision + - risk_assessment + - independent_risk_verdict + - trade_execution_ticket + - execution_confirmation + - original_kpi_evaluation_inputs + + retroactive_rewriting_allowed: false + + corrections: + method: append_only + preserve_original: true + require: + - timestamp + - actor + - reason + - previous_value + - corrected_value + + source_policy: + + material_factual_claims: + source_required: true + + preferred_source_order: + - primary_source + - official_regulator + - official_market_or_exchange + - high_quality_secondary_source + + provenance_required: + - source + - retrieval_time + - relevant_event_time + + decision_record_policy: + + distinguish: + - fact + - interpretation + - assumption + - thesis + - decision + - outcome + - lesson + + principle: > + These categories must remain distinguishable so post-mortem + analysis can determine whether a failure originated from data, + interpretation, process, forecasting, risk management or another + stage of the decision process. + + error_taxonomy: + + DATA_ERROR: + examples: + - incorrect_data + - stale_data + - missing_material_data + + INTERPRETATION_ERROR: + examples: + - causal_error + - expectation_error + - regime_misclassification + + PROCESS_ERROR: + examples: + - missing_required_source + - ignored_contradiction + - sop_violation + + FORECAST_ERROR: + examples: + - wrong_direction + - wrong_timing + - wrong_magnitude + + RISK_ERROR: + examples: + - incorrect_sizing + - ignored_correlation + - inappropriate_stop + - ignored_event_risk + + performance_governance: + + principle: > + Financial outcome and decision quality are not equivalent. + + requirements: + - preserve_pre_outcome_forecast + - evaluate_against_predefined_criteria + - use_coherent_benchmark + - include_sample_size + - include_analysis_period + - include_reliability_assessment + + process_change_policy: + + agent_self_modification: false + + production_change_requires: + - documented_change + - rationale + - historical_or_simulation_test + - responsible_review + - approval + - version_number + + rollback_required: true + + risk_policy: + + numeric_limits_defined: false + + rule: > + Numerical portfolio and trade risk limits must never be invented + by an agent. They will be defined separately and become active + only after explicit CEO approval. From 2c9e2ad2d28823fa491f9be394b4d7cdfab2fa27 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 15:50:30 +0200 Subject: [PATCH 04/62] Add memory policy for Startup Brain This file defines the memory policy for the Startup Brain, outlining its goals, memory scope, reasoning policy, experience model, and retrieval principles. --- policies/memory_policy.yaml | 533 ++++++++++++++++++++++++++++++++++++ 1 file changed, 533 insertions(+) create mode 100644 policies/memory_policy.yaml diff --git a/policies/memory_policy.yaml b/policies/memory_policy.yaml new file mode 100644 index 00000000..6ed97c77 --- /dev/null +++ b/policies/memory_policy.yaml @@ -0,0 +1,533 @@ +startup_brain: + version: "1.0" + + name: Startup Brain + provider: cognee + + definition: > + Cognee is the institutional memory of the company's reasoning, + decisions, experiences and organizational knowledge, preserved + together with the context required to reuse that experience + correctly in the future. + + primary_goal: > + Increase the accumulated experience of the organization so that + agents can learn from previous reasoning, decisions, successes, + failures, reviews, interactions and processes and improve their + future work over time. + + philosophy: + memory_is_not_data_warehouse: true + experience_over_raw_information: true + contextual_learning: true + + core_rule: > + If information can be reliably retrieved again from an external + source and is not required to reconstruct a company decision or + experience, it should normally not consume institutional memory. + + memory_scope: + + store: + - reasoning_summaries + - decision_rationales + - evidence_considered + - assumptions + - interpretations + - alternative_hypotheses + - objections + - decisions + - reviews + - disagreements + - outcomes + - errors + - corrections + - lessons + - success_patterns + - failure_patterns + - employee_evaluations + - kpi_interpretations + - collaboration_experiences + - source_reliability_experiences + - tool_reliability_experiences + - model_reliability_experiences + - workflow_experiences + - process_improvement_experiences + - sop_knowledge + - organizational_knowledge + - company_policies + - contextualized_material_events_used_in_decisions + + do_not_store_by_default: + - historical_price_series + - ohlcv_history + - raw_intraday_candles + - raw_market_volume_history + - complete_order_books + - raw_macro_time_series + - bulk_news_feeds + - reproducible_external_market_data + - unnecessary_external_document_duplicates + + market_data_policy: + + startup_brain_is_market_database: false + + fetch_on_demand: + - current_prices + - historical_prices + - charts + - ohlcv + - market_volume + - volatility_data + - financial_market_time_series + + external_source_preferred: true + + audit_exception: > + A point-in-time observed market value may be stored in an + operational proposal, decision or Trade Execution Ticket when + necessary to reconstruct what information was available at the + moment of the decision. This does not convert market time-series + data into institutional memory. + + reasoning_policy: + + objective: > + Preserve reusable business reasoning and decision rationale + without attempting to store private hidden chain-of-thought. + + store_as_structured_artifact: + - question_or_problem + - context + - evidence + - relevant_facts + - interpretations + - assumptions + - alternatives_considered + - objections + - conclusion + - confidence + - decision + - later_outcome + - lesson_if_any + + experience_model: + + central_entity: Experience + + experience_types: + - market_analysis + - news_interpretation + - investment_decision + - risk_review + - red_team_review + - performance_evaluation + - employee_kpi_review + - collaboration + - tool_usage + - source_evaluation + - model_evaluation + - workflow_execution + - process_failure + - process_success + - post_mortem + - procedure_change + + standard_structure: + - experience_id + - experience_type + - subject + - participants + - context + - inputs + - reasoning_summary + - decision + - action_or_output + - review + - outcome + - feedback + - lesson + - confidence + - sample_size + - created_at + - event_time + - created_by + - reviewed_by + - provenance + - status + + context_envelope: + + purpose: > + Allow experiences to be retrieved because the current situation + is conceptually similar, not only because the same asset, + employee or keyword is involved. + + extensible: true + + possible_dimensions: + - asset_class + - asset + - company + - sector + - geography + - market_regime + - volatility_regime + - macro_regime + - valuation_regime + - liquidity_regime + - company_phase + - event_type + - investment_horizon + - relevant_catalysts + - relevant_risks + - assumptions + - employee_role + - workflow_stage + - task_type + + rule: > + Context fields are applied only when relevant and may evolve + without changing the fundamental memory philosophy. + + knowledge_categories: + + working_memory: + purpose: current_task_context + persistent_by_default: false + + episodic_memory: + purpose: > + Contextualized record of meaningful company experiences. + + semantic_memory: + purpose: > + Consolidated organizational knowledge derived from validated + information and experience. + + procedural_memory: + purpose: > + Approved knowledge about how company work should be performed. + + lifecycle: + + stages: + - RAW_EXPERIENCE + - INTERPRETED_EXPERIENCE + - LESSON_CANDIDATE + - VALIDATED_LESSON + + raw_experience: + trusted_as_general_rule: false + + interpreted_experience: + trusted_as_general_rule: false + + lesson_candidate: + production_rule: false + review_required: true + + validated_lesson: + reusable: true + approved: true + versioned: true + + principle: > + A single experience must not automatically become a general + production rule. + + fact_reasoning_separation: + + required: true + + categories: + + FACT: + description: > + Information supported by an identifiable source. + + INTERPRETATION: + description: > + Meaning assigned to facts by an agent. + + ASSUMPTION: + description: > + Proposition accepted temporarily for the analysis. + + THESIS: + description: > + Structured analytical conclusion or forecast. + + DECISION: + description: > + Action or judgment selected on the basis of the available + reasoning. + + OUTCOME: + description: > + What subsequently happened. + + LESSON: + description: > + Reusable knowledge inferred through retrospective analysis. + + learning_policy: + + learn_from: + - failures + - successes + - neutral_outcomes + - disagreements + - employee_performance + - kpi_evaluations + - source_quality + - tool_performance + - workflow_performance + + success_analysis: + require_context: true + distinguish_skill_from_luck: true + require_repeatability_assessment: true + + failure_analysis: + classify_error_type: true + preserve_original_reasoning: true + + generalization: + sample_size_required: true + context_similarity_required: true + confidence_required: true + + graph_model: + + important_nodes: + - Agent + - Department + - Task + - Experience + - Proposal + - Asset + - Company + - Sector + - Country + - Currency + - Event + - Source + - Claim + - Fact + - Interpretation + - Assumption + - Thesis + - Catalyst + - Risk + - Decision + - Objection + - TradeExecutionTicket + - Position + - Outcome + - Benchmark + - KPI + - Error + - SuccessPattern + - Lesson + - SOP + - SOPVersion + - PromptVersion + - Tool + - ModelVersion + - Report + - Context + + example_relationships: + - Agent_BELONGS_TO_Department + - Agent_CREATED_Proposal + - Proposal_ABOUT_Asset + - Proposal_SUPPORTED_BY_Source + - Proposal_CONTAINS_Thesis + - Proposal_HAS_CONTEXT_Context + - Thesis_BASED_ON_Fact + - Interpretation_INTERPRETS_Fact + - Decision_BASED_ON_Interpretation + - Proposal_CHALLENGED_BY_Objection + - Proposal_GENERATED_TradeExecutionTicket + - Position_ORIGINATED_FROM_TradeExecutionTicket + - Position_RESULTED_IN_Outcome + - Outcome_EVALUATED_AGAINST_Benchmark + - Error_DISCOVERED_IN_Experience + - Error_GENERATED_Lesson + - SuccessPattern_OBSERVED_IN_Experience + - Lesson_PROPOSES_CHANGE_TO_SOP + - Agent_MEASURED_BY_KPI + + prohibited_default_pattern: + - Asset_CONNECTED_TO_THOUSANDS_OF_PRICE_POINTS + + retrieval: + + principle: > + No agent receives the entire Startup Brain. + + full_brain_dump_to_agent: false + + architecture: + path: + - agent + - brain_gateway + - cognee + - relevant_context_only + + brain_gateway_responsibilities: + - identify_requesting_agent + - enforce_role_permissions + - identify_query_intent + - select_memory_scope + - apply_filters + - limit_graph_expansion + - enforce_context_budget + - return_provenance + - log_retrieval + + retrieval_signals: + - semantic_similarity + - keyword_similarity + - structured_filters + - graph_relationships + - temporal_relevance + - contextual_similarity + + retrieval_modes: + + FAST: + target_result_count: "5-10" + intended_use: simple_context + + STANDARD: + target_result_count: "20-30" + intended_use: normal_agent_work + + DEEP: + target_result_count: "50+" + intended_use: complex_investigation + graph_expansion: limited + + intent_routing: + + principle: > + Questions must be routed to the appropriate source before + retrieval. + + examples: + + historical_price_question: + destination: market_data_provider + + current_price_question: + destination: market_data_provider + + previous_company_reasoning_question: + destination: cognee + + latest_company_filing_question: + destination: external_document_source + + previous_failure_plus_current_conditions: + destinations: + - cognee + - external_information_sources + + permissions: + + direct_agent_database_access: false + direct_agent_unrestricted_brain_access: false + + brain_access: + role_based: true + query_based: true + logged: true + + permanent_memory_write: + unrestricted_agent_write: false + review_required_for_validated_lessons: true + + provenance: + + required_when_relevant: + - source + - source_quality + - creator + - creation_time + - event_time + - verification_status + - confidence + - version + + time_model: + + changing_facts_must_not_be_timeless: true + + optional_fields: + - valid_from + - valid_to + - event_time + - observed_at + + observability_separation: + + cognee: + stores: > + What the company learned, reasoned, decided and how knowledge + relates. + + operational_database: + preferred_provider: postgresql + stores: > + What officially happened operationally. + + object_storage: + preferred_type: s3_compatible + stores: > + Large files and artifacts intentionally retained by the + company. + + observability: + preferred: + - langfuse + - opentelemetry + + stores: > + How agents performed their computation, including model calls, + tool calls, latency, cost, errors and technical traces. + + learning_loop: + + sequence: + - task + - agent_output + - review + - decision + - real_outcome + - process_evaluation + - experience_creation + - lesson_candidate + - evidence_analysis + - historical_or_simulation_testing + - approval + - validated_lesson + - sop_or_prompt_change + - versioning + - monitoring + - confirmation_or_rollback + + non_negotiable_rules: + + - startup_brain_is_not_market_data_warehouse + - raw_retrievable_market_data_does_not_enter_brain_by_default + - preserve_contextualized_reasoning_experience + - preserve_successes_and_failures + - distinguish_fact_interpretation_decision_outcome + - no_single_event_automatic_generalization + - no_agent_reads_entire_brain + - no_unreviewed_lesson_becomes_production_rule + - provenance_must_be_preserved + - company_experience_should_accumulate_over_time From b578267c0ca1c6c7ecbea828af06c17330433478 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 19:27:18 +0200 Subject: [PATCH 05/62] Replace FounderOS demo organization with investment company roster --- lib/seed.ts | 547 ++++++++++++++++++++++------------------------------ 1 file changed, 229 insertions(+), 318 deletions(-) diff --git a/lib/seed.ts b/lib/seed.ts index 5f19983f..7c120a5c 100644 --- a/lib/seed.ts +++ b/lib/seed.ts @@ -37,12 +37,30 @@ const GRAY = { // Alex's five operating pillars (2026-06-12 directive). const departments: Department[] = [ - { id: 'dept-sales', name: 'Sales', slug: 'sales', tagline: 'Pipeline and deals.', color: GRAY.white, order: 1 }, - { id: 'dept-marketing-growth', name: 'Marketing/Growth', slug: 'marketing-growth', tagline: 'Publishing, content, attention.', color: GRAY.light, order: 2 }, - { id: 'dept-tech', name: 'TECH', slug: 'tech', tagline: 'AI & automations · G-Brain.', color: GRAY.mid, order: 3 }, - { id: 'dept-finance', name: 'Finances', slug: 'finances', tagline: 'Every processor, one view.', color: GRAY.dim, order: 4 }, - { id: 'dept-comms', name: 'Communications', slug: 'communications', tagline: 'Gmail, WhatsApp, Slack → one feed.', color: GRAY.dark, order: 5 }, - { id: 'dept-clients', name: 'Clients', slug: 'clients', tagline: 'Every client, onboarded and served.', color: GRAY.light, order: 6 }, + { + id: 'dept-research', + name: 'Research Investments', + slug: 'research-investments', + tagline: 'Investment research across equities, ETFs and crypto.', + color: GRAY.white, + order: 1, + }, + { + id: 'dept-risk', + name: 'Risk Analysis', + slug: 'risk-analysis', + tagline: 'Portfolio risk, trade structure and independent review.', + color: GRAY.light, + order: 2, + }, + { + id: 'dept-monitoring', + name: 'Portfolio Monitoring & Performance', + slug: 'portfolio-monitoring-performance', + tagline: 'Portfolio oversight, performance, KPI and organizational learning.', + color: GRAY.mid, + order: 3, + }, ]; // The roster IS the runtime — every row here maps 1:1 to a RuntimeAgent in @@ -54,401 +72,294 @@ const departments: Department[] = [ // Worker rows underneath them do one specific task each and sit at the // bottom of the hierarchy. const agents: Agent[] = [ - // ── TECH: AI head ───────────────────────────────────────────────────────────────────────────────────────────────────────────── - { - id: 'conductor', - departmentId: 'dept-tech', - name: 'Conductor', - role: 'Broadcast & Orchestration', - status: 'active', - tier: 'lead', - description: 'Fans your message out to every agent at once and checks which instance hosts (Clawline, Ollama, tmux) are available for future bindings.', - model: 'fan-out runtime', - tools: ['broadcast', 'clawline', 'tmux'], - parentId: null, - instance: 'builtin', - }, - // ── Communications: one instance, three channel workers feeding /comms ──────── - { - id: 'comms-agent', - departmentId: 'dept-comms', - name: 'Comms Agent', - role: 'Unified Communications Instance', - status: 'active', - tier: 'lead', - description: 'Owns the unified /comms feed. Aggregates its three channel workers and reports which are live.', - model: 'aggregate of workers', - tools: ['comms-feed'], - parentId: null, - instance: 'builtin', - }, + // ── RESEARCH INVESTMENTS ───────────────────────────────────────────── + { - id: 'gmail-worker', - departmentId: 'dept-comms', - name: 'Gmail Worker', - role: 'IMAP Inboxes ×4', + id: 'djed', + departmentId: 'dept-research', + name: 'Djed', + role: 'Macro & Geopolitical Desk', status: 'planned', - tier: 'worker', - description: 'Pulls unread counts and recent mail from up to four IMAP inboxes into /comms. Activates when INBOX_* creds land.', - model: 'imapflow', - tools: ['imap'], - parentId: 'comms-agent', - instance: 'builtin', - }, - { - id: 'whatsapp-worker', - departmentId: 'dept-comms', - name: 'WhatsApp Worker', - role: 'Chat Monitor', - status: 'active', - tier: 'worker', - description: 'Reads the local WhatsApp ChatStorage (local team chats) into /comms. Works today.', - model: 'local sqlite (read-only)', - tools: ['whatsapp'], - parentId: 'comms-agent', + tier: 'specialist', + description: + 'Maintains the global macroeconomic and geopolitical view and supports sector researchers with rates, inflation, central banks, currencies, energy and geopolitical risk.', + model: 'unassigned', + tools: ['startup-brain', 'macro-data', 'web-research'], + parentId: 'beppe', instance: 'builtin', }, + { - id: 'slack-worker', - departmentId: 'dept-comms', - name: 'Slack Worker', - role: 'Channel Digest', + id: 'marcus', + departmentId: 'dept-research', + name: 'Marcus', + role: 'Market News Desk', status: 'planned', - tier: 'worker', - description: 'Latest messages across joined channels into /comms. Needs SLACK_BOT_TOKEN.', - model: '@slack/web-api', - tools: ['slack'], - parentId: 'comms-agent', - instance: 'builtin', - }, - // ── Marketing/Growth: social/content crew ─────────────────────────── - { - id: 'social-agent', - departmentId: 'dept-marketing-growth', - name: 'Social Agent', - role: 'Social Media & Content Creation Instance', - status: 'active', - tier: 'lead', - description: 'Owns publishing and content production. Aggregates the Postly and Adsmith workers.', - model: 'aggregate of workers', - tools: ['postly', 'adsmith', 'reelkit', 'renderly', 'dmflow'], - parentId: null, - instance: 'builtin', - }, - { - id: 'postly-publisher', - departmentId: 'dept-marketing-growth', - name: 'Postly Publisher', - role: 'Six-Platform Publishing', - status: 'active', - tier: 'worker', - description: 'Publishes and monitors six platforms under @founderos.ai via Postly. Key already on this machine — works today.', - model: 'postly api', - tools: ['postly'], - parentId: 'social-agent', - instance: 'builtin', - }, - { - id: 'adsmith-creative', - departmentId: 'dept-marketing-growth', - name: 'Adsmith Creative', - role: 'UGC Ad Generation', - status: 'active', - tier: 'worker', - description: 'Generates UGC ads for Vantage (Veo/Sora/Kling) via the Adsmith API. Auth on this machine — works today.', - model: 'adsmith api', - tools: ['adsmith'], - parentId: 'social-agent', - instance: 'builtin', - }, - { - id: 'reelkit-editor', - departmentId: 'dept-marketing-growth', - name: 'Reelkit Editor', - role: 'Social Editing Pipeline', - status: 'active', - tier: 'worker', - description: 'Editing and rendering pipeline for social media clips, captions, and promotional cuts.', - model: 'reelkit pipeline', - tools: ['reelkit', 'whisper'], - parentId: 'social-agent', + tier: 'specialist', + description: + 'Monitors company and sector news, M&A, regulation, catalysts and material events and supports investment researchers with timely information.', + model: 'unassigned', + tools: ['startup-brain', 'news', 'web-research'], + parentId: 'beppe', instance: 'builtin', }, + { - id: 'renderly-creative', - departmentId: 'dept-marketing-growth', - name: 'Renderly Creative', - role: 'AI Creative Studio', - status: 'active', + id: 'lauti', + departmentId: 'dept-research', + name: 'Lauti', + role: 'Equity Research Desk', + status: 'planned', tier: 'worker', - description: 'Renderly creative generation for social assets, product shots, and campaign visuals.', - model: 'renderly cli', - tools: ['renderly'], - parentId: 'social-agent', + description: + 'Researches listed equities using fundamental, financial and technical analysis and produces investment proposals when conviction is sufficient.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'financial-statements', 'web-research'], + parentId: 'beppe', instance: 'builtin', }, + { - id: 'dmflow-mcp', - departmentId: 'dept-marketing-growth', - name: 'DMFlow MCP', - role: 'DM Automation', + id: 'pepo', + departmentId: 'dept-research', + name: 'Pepo', + role: 'Crypto Research Desk', status: 'planned', tier: 'worker', - description: 'DMFlow MCP/API lane for social DM automations, keyword flows, and lead capture.', - model: 'dmflow api', - tools: ['dmflow'], - parentId: 'social-agent', - instance: 'builtin', - }, - { - id: 'sales-agent', - departmentId: 'dept-sales', - name: 'Sales Agent', - role: 'Deals & Pipeline Instance', - status: 'active', - tier: 'lead', - description: 'Owns the sales pillar. Aggregates CRM Pulse and reports the live Ledger deals pipeline.', - model: 'aggregate of workers', - tools: ['ledger', 'paykit', 'stripe', 'flexpay', 'recall'], - parentId: null, + description: + 'Researches cryptocurrencies using market structure, tokenomics, protocol analysis, liquidity, regulation and security analysis.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'crypto-data', 'web-research'], + parentId: 'beppe', instance: 'builtin', }, + { - id: 'launchpad-cohort-sales', - departmentId: 'dept-sales', - name: 'Launchpad Cohort', - role: 'Sales Account Lane', + id: 'andy', + departmentId: 'dept-research', + name: 'Andy', + role: 'ETF Research Desk', status: 'planned', tier: 'worker', - description: 'Launchpad Cohort sales lane: offers, calls, payment confirmation, and CRM context.', - model: 'account lane', - tools: ['ledger', 'stripe', 'paykit'], - parentId: 'sales-agent', + description: + 'Researches ETFs through index composition, holdings, costs, tracking error, concentration, liquidity and technical analysis.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'etf-data', 'web-research'], + parentId: 'beppe', instance: 'builtin', }, + { - id: 'vantage-sales', - departmentId: 'dept-sales', - name: 'Vantage', - role: 'Sales Account Lane', + id: 'yann', + departmentId: 'dept-research', + name: 'Yann', + role: 'Red Desk', status: 'planned', - tier: 'worker', - description: 'Vantage sales lane: account pipeline, PayKit context, payment confirmation, and call data.', - model: 'account lane', - tools: ['ledger', 'stripe', 'paykit'], - parentId: 'sales-agent', + tier: 'specialist', + description: + 'Independently challenges investment proposals, identifying material weaknesses, unsupported assumptions, contradictions and overlooked risks.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'web-research'], + parentId: 'beppe', instance: 'builtin', }, + { - id: 'paykit-sales', - departmentId: 'dept-finance', - name: 'PayKit', - role: 'Offer & Payment Platform', + id: 'beppe', + departmentId: 'dept-research', + name: 'Beppe', + role: 'Final Research Supervisor', status: 'planned', - tier: 'worker', - description: 'PayKit sales platform connection for offers and customer/payment context.', - model: 'paykit api', - tools: ['paykit'], - parentId: 'payments-pulse', + tier: 'lead', + description: + 'Final supervisor of the Research Investments Team and the team’s official interface with the CEO.', + model: 'unassigned', + tools: ['startup-brain', 'proposal-registry'], + parentId: null, instance: 'builtin', }, + + // ── RISK ANALYSIS ──────────────────────────────────────────────────── + { - id: 'vantage-paykit', - departmentId: 'dept-sales', - name: 'Vantage PayKit', - role: 'Vantage PayKit Lane', + id: 'manuel', + departmentId: 'dept-risk', + name: 'Manuel', + role: 'Portfolio Risk Manager', status: 'planned', tier: 'worker', - description: 'PayKit lane specifically under Vantage for offer, payment, and customer context.', - model: 'paykit api', - tools: ['paykit'], - parentId: 'vantage-sales', + description: + 'Evaluates portfolio-level sustainability, concentration, correlations, liquidity and maximum permissible capital allocation.', + model: 'unassigned', + tools: ['startup-brain', 'portfolio-data', 'market-data'], + parentId: 'christian', instance: 'builtin', }, + { - id: 'stripe-sales', - departmentId: 'dept-finance', - name: 'Stripe', - role: 'Sales Payment Processor', + id: 'dimash', + departmentId: 'dept-risk', + name: 'Dimash', + role: 'Trade Structuring Analyst', status: 'planned', tier: 'worker', - description: 'Stripe payment confirmation lane for sales workflows and account-level revenue checks.', - model: 'stripe sdk', - tools: ['stripe'], - parentId: 'payments-pulse', + description: + 'Transforms approved investment ideas into concrete entry, sizing, stop, target, duration and risk-reward structures.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'portfolio-data'], + parentId: 'christian', instance: 'builtin', }, + { - id: 'processor-confirmation', - departmentId: 'dept-finance', - name: 'Processor Confirm', - role: 'Payment API Confirmation', + id: 'bare', + departmentId: 'dept-risk', + name: 'Bare', + role: 'Liquidity and Event Risk Analyst', status: 'planned', tier: 'worker', - description: 'APIs to payment processors for confirming paid, failed, disputed, and pending states.', - model: 'processor registry', - tools: ['stripe', 'paypal', 'square', 'whop', 'paykit'], - parentId: 'payments-pulse', + description: + 'Evaluates spread, depth, liquidity, execution quality and material event risks before a trade can proceed.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'event-calendar', 'news'], + parentId: 'christian', instance: 'builtin', }, + { - id: 'flexpay-financing', - departmentId: 'dept-finance', - name: 'FlexPay Financing', - role: 'Financing Options', + id: 'angelo', + departmentId: 'dept-risk', + name: 'Angelo', + role: 'Broker Execution Specialist', status: 'planned', tier: 'worker', - description: 'FlexPay financing options lane for sales offers and payment-plan context.', - model: 'flexpay api', - tools: ['flexpay'], - parentId: 'payments-pulse', + description: + 'Converts the approved financial plan into broker-neutral manual execution instructions for the CEO.', + model: 'unassigned', + tools: ['startup-brain', 'instrument-reference'], + parentId: 'christian', instance: 'builtin', }, + { - id: 'sales-calls-data', - departmentId: 'dept-sales', - name: 'Sales Calls Data', - role: 'Call Intelligence', + id: 'pio', + departmentId: 'dept-risk', + name: 'Pio', + role: 'Independent Risk Controller', status: 'planned', - tier: 'worker', - description: 'Sales calls data lane for recordings, notes, outcomes, and follow-up context.', - model: 'recall + crm', - tools: ['recall', 'ledger'], - parentId: 'sales-agent', + tier: 'specialist', + description: + 'Independently reviews calculations, sources, portfolio constraints, event risks and trade structure before final approval.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'portfolio-data'], + parentId: 'christian', instance: 'builtin', }, - // ── TECH: the G-Brain data analyst and its auditors ────────────────────────────── + { - id: 'data-agent', - departmentId: 'dept-tech', - name: 'Data Agent', - role: 'G-Brain Analyst', - status: 'active', + id: 'christian', + departmentId: 'dept-risk', + name: 'Christian', + role: 'Final Risk Supervisor', + status: 'planned', tier: 'lead', - description: 'Bound to the G-Brain instance: analyzes markdown + vector storage health and surfaces ideas. Answers broadcasts by querying the brain.', - model: 'gbrain CLI', - tools: ['gbrain', 'brain-store', 'zeroentropy', 'supabase'], + description: + 'Final supervisor of the Risk Analysis Team and the team’s official interface with the CEO.', + model: 'unassigned', + tools: ['startup-brain', 'trade-ticket-registry'], parentId: null, instance: 'builtin', }, + + // ── PORTFOLIO MONITORING & PERFORMANCE ─────────────────────────────── + { - id: 'markdown-auditor', - departmentId: 'dept-tech', - name: 'Markdown Auditor', - role: 'brain-store Health', - status: 'active', + id: 'john', + departmentId: 'dept-monitoring', + name: 'John', + role: 'Position Monitoring Desk', + status: 'planned', tier: 'worker', - description: 'Walks the markdown brain-store: page counts per folder, strays at the root, empty folders. Works today.', - model: 'fs walk', - tools: ['brain-store'], - parentId: 'data-agent', + description: + 'Monitors open positions against market conditions, news, technical developments, thesis validity and original trade tickets.', + model: 'unassigned', + tools: ['startup-brain', 'market-data', 'portfolio-data', 'news'], + parentId: 'javier', instance: 'builtin', }, + { - id: 'vector-auditor', - departmentId: 'dept-tech', - name: 'Vector Auditor', - role: 'pgvector / Supabase Health', - status: 'active', + id: 'ale', + departmentId: 'dept-monitoring', + name: 'Ale', + role: 'Portfolio Exposure and Event Watch', + status: 'planned', tier: 'worker', - description: 'Runs gbrain doctor: connection to Supabase pgvector, embedding checks, health score. Works today.', - model: 'gbrain doctor', - tools: ['supabase', 'zeroentropy'], - parentId: 'data-agent', + description: + 'Monitors portfolio exposure, concentration, correlations, drawdown, liquidity and the unified event calendar.', + model: 'unassigned', + tools: ['startup-brain', 'portfolio-data', 'market-data', 'event-calendar'], + parentId: 'javier', instance: 'builtin', }, + { - id: 'notion-sync', - departmentId: 'dept-tech', - name: 'Notion Sync', - role: 'Workspace Reader', + id: 'carlos', + departmentId: 'dept-monitoring', + name: 'Carlos', + role: 'Performance Analytics Desk', status: 'planned', - tier: 'specialist', - description: 'Recently edited pages shared with the integration. Needs NOTION_API_KEY.', - model: '@notionhq/client', - tools: ['notion'], - parentId: 'data-agent', + tier: 'worker', + description: + 'Measures proposal, trade and decision outcomes against expectations, benchmarks, risk and costs.', + model: 'unassigned', + tools: ['startup-brain', 'portfolio-data', 'performance-data'], + parentId: 'javier', instance: 'builtin', }, - // ── Finances ────────────────────────────────────────────────────────────────────────────────────────────────────────────────── + { - id: 'payments-pulse', - departmentId: 'dept-finance', - name: 'Payments Pulse', - role: 'Processor Monitor', + id: 'hakan', + departmentId: 'dept-monitoring', + name: 'Hakan', + role: 'Employee KPI and Audit Desk', status: 'planned', - tier: 'lead', - description: 'Stripe balance + recent charges; PayPal/Square/Whop registered and awaiting keys.', - model: 'stripe sdk', - tools: ['stripe', 'paypal', 'square', 'whop'], - parentId: null, - instance: 'builtin', - }, - { - id: 'crm-pulse', - departmentId: 'dept-sales', - name: 'Ledger CRM', - role: 'ATTO / Ledger Deals Pipeline', - status: 'active', tier: 'worker', - description: 'Vantage + LC deals from Ledger, key reused from the MCP config. Works today.', - model: 'ledger api', - tools: ['ledger'], - parentId: 'sales-agent', - instance: 'builtin', - }, - // ── TECH: automations ───────────────────────────────────────────────────────────────────────────────────────────────────── - { - id: 'stack-monitor', - departmentId: 'dept-tech', - name: 'Stack Monitor', - role: 'Local Stack Health', - status: 'active', - tier: 'lead', - description: 'Reelkit, Ollama, command-center, Clawline, tmux, whisper, ffmpeg, renderly, gh + Dictate Flow stats.', - model: 'local checks', - tools: ['reelkit', 'ollama', 'tmux', 'dictate'], - parentId: null, - instance: 'builtin', - }, - // ── Clients: roster, onboarding, service ────────────────────────────────── - { - id: 'client-roster', - departmentId: 'dept-clients', - name: 'Client Roster', - role: 'Live Client List', - status: 'active', - tier: 'lead', - description: 'The single source of truth for who is a client: reconciles Ledger and PayKit against the funnel and keeps the roster current.', - model: 'funnel + Ledger', - tools: ['ledger', 'paykit'], - parentId: null, + description: + 'Evaluates each AI employee using role-specific scorecards covering quality, compliance, sources, timeliness, collaboration and errors.', + model: 'unassigned', + tools: ['startup-brain', 'agent-logs', 'performance-data'], + parentId: 'javier', instance: 'builtin', }, + { - id: 'client-onboarding', - departmentId: 'dept-clients', - name: 'Onboarding Agent', - role: 'Closed-Won to Kickoff', + id: 'zielu', + departmentId: 'dept-monitoring', + name: 'Zielu', + role: 'Learning and Process Improvement Desk', status: 'planned', tier: 'worker', - description: 'Runs the onboarding SOP end to end when a deal closes: welcome pack, workspace setup, kickoff booked, handoff notes.', - model: 'ledger + slack + notion', - tools: ['ledger', 'slack', 'notion'], - parentId: 'client-roster', + description: + 'Performs post-mortems, identifies recurring patterns and proposes tested and versioned improvements to SOPs, prompts, tools and sources.', + model: 'unassigned', + tools: ['startup-brain', 'agent-logs', 'performance-data'], + parentId: 'javier', instance: 'builtin', }, + { - id: 'client-success', - departmentId: 'dept-clients', - name: 'Client Success', - role: 'Service & Renewals', + id: 'javier', + departmentId: 'dept-monitoring', + name: 'Javier', + role: 'Final Monitoring Supervisor', status: 'planned', - tier: 'worker', - description: 'Keeps active clients served: check-in cadence, deliverable tracking from call notes, renewal and upsell flags.', - model: 'recall + slack', - tools: ['recall', 'slack'], - parentId: 'client-roster', + tier: 'lead', + description: + 'Final supervisor of Portfolio Monitoring and Performance Control and the team’s official interface with the CEO.', + model: 'unassigned', + tools: ['startup-brain', 'portfolio-data', 'agent-logs'], + parentId: null, instance: 'builtin', }, ]; From 8a343ef72963a339df5470276ecc1023f7dd192c Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 19:30:11 +0200 Subject: [PATCH 06/62] Register investment company agent runtimes Refactor agent creation to use plannedAgentRun for unconnected agents and createPlannedAgent for new agents, consolidating agent definitions. --- lib/agents/real.ts | 672 ++++++++++----------------------------------- 1 file changed, 151 insertions(+), 521 deletions(-) diff --git a/lib/agents/real.ts b/lib/agents/real.ts index 2032d20f..a50d22b8 100644 --- a/lib/agents/real.ts +++ b/lib/agents/real.ts @@ -1,531 +1,161 @@ -import { z } from 'zod'; -import { getBrainProvider } from '@/lib/brain'; -import { createGBrainProvider } from '@/lib/connectors/gbrain'; -import { parseInboxConfigs, unreadCounts } from '@/lib/connectors/email'; -import { configuredProcessors, stripeSnapshot } from '@/lib/connectors/payments'; -import { recentMessages } from '@/lib/connectors/slack'; -import { recentPages } from '@/lib/connectors/notion'; -import { zernioStatus } from '@/lib/connectors/zernio'; -import { attioClients, attioStatus } from '@/lib/connectors/attio'; -import { webinarjamStatus, listRegistrants } from '@/lib/connectors/webinarjam'; -import { trakyoStatus } from '@/lib/connectors/trakyo'; -import { arcadsStatus } from '@/lib/connectors/arcads'; -import { whatsappStatus } from '@/lib/connectors/whatsapp'; -import { wisprStatus } from '@/lib/connectors/wispr'; -import { localStackStatus } from '@/lib/connectors/local-stack'; -import { getDb } from '@/lib/data'; -import type { LlmToolSpec } from '@/lib/connectors/llm'; import type { AgentRunResult, RuntimeAgent } from '@/lib/agents/runtime'; -/** - * The real agent roster. Every run() does actual work against a live system — - * no seeded numbers. Agents whose connector lacks credentials fail honestly - * with setup instructions instead of pretending. - * - * Top-level agents are instance slots: when the dedicated host is live each one - * becomes its own Clawline / Claude Code process and respond() routes - * to that instance instead of the builtin implementation. - */ - -async function gmailRun(): Promise { - const inboxes = parseInboxConfigs(process.env); - if (inboxes.length === 0) { - return { ok: false, summary: 'No inboxes configured — set INBOX_1..4_HOST/_USER/_PASS in .env.local' }; - } - const counts = await unreadCounts(process.env); - const failed = counts.filter((c) => c.error); - const total = counts.reduce((sum, c) => sum + c.unread, 0); - return { - ok: failed.length < counts.length, - summary: counts - .map((c) => `${c.inbox}: ${c.error ? `ERROR ${c.error.slice(0, 60)}` : `${c.unread} unread`}`) - .join(' · ') - .concat(` · total ${total} unread`), - data: counts, - }; -} - -async function whatsappRun(): Promise { - const status = await whatsappStatus(); - return { ok: status.state === 'connected', summary: status.detail, data: status.meta }; -} - -async function slackRun(): Promise { - if (!process.env.SLACK_BOT_TOKEN) { - return { ok: false, summary: 'Slack not configured — set SLACK_BOT_TOKEN in .env.local' }; - } - const messages = await recentMessages(10); - return { - ok: true, - summary: `${messages.length} recent messages across ${new Set(messages.map((m) => m.channel)).size} channels`, - data: messages, - }; -} - -async function zernioRun(): Promise { - const status = await zernioStatus(); - return { ok: status.state === 'connected', summary: status.detail, data: status.meta }; -} - -async function arcadsRun(): Promise { - const status = await arcadsStatus(); - return { ok: status.state === 'connected', summary: status.detail, data: status.meta }; -} - -const label = (r: AgentRunResult) => (r.ok ? 'LIVE' : 'DOWN'); - -const envIntegrationRun = - (name: string, envKey: string, purpose: string) => - async (): Promise => { - if (!process.env[envKey]) { - return { ok: false, summary: `${name} not configured — set ${envKey} · ${purpose}` }; - } - return { ok: true, summary: `${name} credential present · ${purpose}` }; - }; - -const plannedLaneRun = - (name: string, detail: string) => - async (): Promise => ({ ok: false, summary: `${name} lane planned — ${detail}` }); - -async function stripeSalesRun(): Promise { - if (!process.env.STRIPE_SECRET_KEY) { - return { ok: false, summary: 'Stripe sales checks not configured — set STRIPE_SECRET_KEY in .env.local' }; - } - const snapshot = await stripeSnapshot(process.env); - return { - ok: true, - summary: `Stripe sales payments: ${snapshot.recentCharges.length} recent charges available for confirmation`, - data: snapshot, - }; +function plannedAgentRun(name: string, role: string) { + return async (): Promise => ({ + ok: false, + summary: `${name} (${role}) is registered in the company but its production runtime is not connected yet.`, + }); } -async function processorConfirmationRun(): Promise { - const configured = configuredProcessors(process.env).filter((p) => p.configured); - if (configured.length === 0) { - return { ok: false, summary: 'No payment processor APIs configured yet — start with STRIPE_SECRET_KEY' }; - } +function createPlannedAgent( + id: string, + name: string, + description: string, + departmentId: string, +): RuntimeAgent { return { - ok: true, - summary: `${configured.map((p) => p.name).join(', ')} configured for payment confirmation`, - data: configured, + id, + name, + description, + departmentId, + run: plannedAgentRun(name, description), }; } export const realAgents: RuntimeAgent[] = [ - // ── Command ────────────────────────────────────────────────────────── - { - id: 'conductor', - name: 'Conductor', - description: 'Broadcast fan-out + instance host availability (Clawline gateway, Ollama, tmux) for future bindings.', - departmentId: 'dept-tech', - async run() { - const stack = await localStackStatus(); - return { - ok: stack.state === 'connected', - summary: `Instance hosts on this machine: ${stack.detail} · all agents bound to builtin runtime until the dedicated host lands`, - data: stack.meta, - }; - }, - }, - - // ── Comms instance + channel workers ───────────────────────────────── - { - id: 'comms-agent', - name: 'Comms Agent', - description: 'Aggregates the Gmail/WhatsApp/Slack workers that feed the unified /comms view.', - departmentId: 'dept-comms', - async run() { - const [gmail, whatsapp, slack] = await Promise.all([gmailRun(), whatsappRun(), slackRun()]); - const live = [gmail, whatsapp, slack].filter((r) => r.ok).length; - return { - ok: live > 0, - summary: `${live}/3 channels live → /comms · Gmail ${label(gmail)} · WhatsApp ${label(whatsapp)} · Slack ${label(slack)}`, - data: { gmail, whatsapp, slack }, - }; - }, - }, - { id: 'gmail-worker', name: 'Gmail Worker', description: 'Unread counts and recent mail from up to four IMAP inboxes.', departmentId: 'dept-comms', run: gmailRun }, - { id: 'whatsapp-worker', name: 'WhatsApp Worker', description: 'Local WhatsApp ChatStorage, read-only.', departmentId: 'dept-comms', run: whatsappRun }, - { id: 'slack-worker', name: 'Slack Worker', description: 'Latest messages across joined Slack channels.', departmentId: 'dept-comms', run: slackRun }, - - // ── Studio instance + content workers ──────────────────────────────── - { - id: 'social-agent', - name: 'Social Agent', - description: 'Aggregates the Postly publishing and Adsmith ad-generation workers.', - departmentId: 'dept-marketing-growth', - async run() { - const [postly, adsmith] = await Promise.all([zernioRun(), arcadsRun()]); - const live = [postly, adsmith].filter((r) => r.ok).length; - const queued = getDb().socialPosts.queued().length; - const queueNote = queued > 0 ? `${queued} post${queued === 1 ? '' : 's'} queued for publish` : 'no posts queued'; - return { - ok: live > 0, - summary: `${live}/2 core content APIs live · Postly ${label(postly)} · Adsmith ${label(adsmith)} · ${queueNote}`, - data: { postly, adsmith, queuedPosts: queued }, - }; - }, - }, - { id: 'postly-publisher', name: 'Postly Publisher', description: 'Six platforms under @founderos.ai via Postly.', departmentId: 'dept-marketing-growth', run: zernioRun }, - { id: 'adsmith-creative', name: 'Adsmith Creative', description: 'UGC ads for Vantage via the Adsmith API.', departmentId: 'dept-marketing-growth', run: arcadsRun }, - { - id: 'reelkit-editor', - name: 'Reelkit Editor', - description: 'Editing and rendering pipeline for social clips, captions, and promotional cuts.', - departmentId: 'dept-marketing-growth', - async run() { - const stack = await localStackStatus(); - return { - ok: stack.state === 'connected', - summary: `Reelkit/social editing lane mapped · local stack: ${stack.detail}`, - data: stack.meta, - }; - }, - }, - { - id: 'renderly-creative', - name: 'Renderly Creative', - description: 'Renderly creative generation for campaign visuals and product assets.', - departmentId: 'dept-marketing-growth', - async run() { - const stack = await localStackStatus(); - return { - ok: stack.state === 'connected', - summary: `Renderly creative lane mapped · local stack: ${stack.detail}`, - data: stack.meta, - }; - }, - }, - { - id: 'dmflow-mcp', - name: 'DMFlow MCP', - description: 'DMFlow MCP/API lane for social DM automations and lead capture.', - departmentId: 'dept-marketing-growth', - run: envIntegrationRun('DMFlow', 'MANYCHAT_API_KEY', 'DM automation and lead capture'), - }, - - // ── Sales instance + pipeline worker ───────────────────────────────── - { - id: 'sales-agent', - name: 'Sales Agent', - description: 'Aggregates the revenue pipeline workers for Sales.', - departmentId: 'dept-sales', - async run() { - const [crm, processors] = await Promise.all([attioStatus(), processorConfirmationRun()]); - return { - ok: crm.state === 'connected' || processors.ok, - summary: `Sales pipeline · Ledger ${crm.state === 'connected' ? 'LIVE' : 'DOWN'} · processors ${label(processors)} · PayKit/FlexPay/calls lanes mapped`, - data: { crm, processors }, - }; - }, - }, - { - id: 'launchpad-cohort-sales', - name: 'Launchpad Cohort', - description: - 'Launchpad Cohort sales lane: WebinarJam funnel (registrants/attendees → leads), Trakyo revenue attribution, plus offer/call/payment context.', - departmentId: 'dept-sales', - async run() { - const [webinar, trakyo] = await Promise.all([webinarjamStatus(), trakyoStatus()]); - const live = [webinar, trakyo].filter((s) => s.state === 'connected').length; - return { - ok: live > 0, - summary: `Launchpad Cohort · WebinarJam ${webinar.state} · Trakyo ${trakyo.state}${ - live === 0 ? ' — set WEBINARJAM_API_KEY to pull webinar leads' : '' - }`, - data: { webinar, trakyo }, - }; - }, - chatTools(): LlmToolSpec[] { - return [ - { - name: 'searchWebinarRegistrants', - description: - "List registrants/attendees for an Launchpad Cohort WebinarJam session (these are leads). Read-only. Needs the webinar's id and schedule id.", - parameters: z.object({ - webinarId: z.string().describe('WebinarJam webinar_id'), - scheduleId: z.string().describe('WebinarJam schedule_id for the session'), - }), - execute: async (args) => { - const webinarId = typeof args.webinarId === 'string' ? args.webinarId : ''; - const scheduleId = typeof args.scheduleId === 'string' ? args.scheduleId : ''; - if (!webinarId || !scheduleId) return { error: 'webinarId and scheduleId are required' }; - const registrants = await listRegistrants(webinarId, scheduleId); - return { count: registrants.length, registrants: registrants.slice(0, 25) }; - }, - }, - ]; - }, - }, - { - id: 'vantage-sales', - name: 'Vantage', - description: 'Vantage sales lane: pipeline, PayKit context, payments, and call data.', - departmentId: 'dept-sales', - run: plannedLaneRun('Vantage sales', 'connect Vantage-specific CRM/payment/call sources'), - }, - { - id: 'paykit-sales', - name: 'PayKit', - description: 'PayKit offer/payment/customer context for Sales.', - departmentId: 'dept-sales', - run: envIntegrationRun('PayKit', 'FANBASIS_API_KEY', 'offers, customers, and payment context'), - }, - { - id: 'vantage-paykit', - name: 'Vantage PayKit', - description: 'PayKit lane specifically under Vantage.', - departmentId: 'dept-sales', - run: envIntegrationRun('Vantage PayKit', 'FANBASIS_API_KEY', 'Vantage offer/payment context'), - }, - { id: 'stripe-sales', name: 'Stripe', description: 'Stripe payment confirmation for sales workflows.', departmentId: 'dept-sales', run: stripeSalesRun }, - { - id: 'processor-confirmation', - name: 'Processor Confirm', - description: 'Confirms payment states across configured processor APIs.', - departmentId: 'dept-sales', - run: processorConfirmationRun, - }, - { - id: 'flexpay-financing', - name: 'FlexPay Financing', - description: 'FlexPay financing options for offers and payment plans.', - departmentId: 'dept-sales', - run: envIntegrationRun('FlexPay', 'FlexPay_API_KEY', 'financing options for sales offers'), - }, - { - id: 'sales-calls-data', - name: 'Sales Calls Data', - description: 'Sales call recordings, notes, outcomes, and follow-up context.', - departmentId: 'dept-sales', - run: envIntegrationRun('Sales calls data', 'FATHOM_API_KEY', 'call recordings, summaries, and follow-up context'), - }, - - // ── Knowledge: the G-Brain analyst and its auditors ────────────────── - { - id: 'data-agent', - name: 'Data Agent', - description: 'Analyzes markdown + vector storage health and surfaces ideas; answers broadcasts by querying G-Brain.', - departmentId: 'dept-tech', - async run() { - const overview = await createGBrainProvider().overview(); - const { store, doctor } = overview; - const warnings = doctor.checks.filter((c) => c.status !== 'ok'); - const biggest = [...store.folders].sort((a, b) => b.files - a.files)[0]; - const inbox = store.folders.find((f) => f.name === 'inbox'); - - const ideas: string[] = []; - if (!doctor.connected) ideas.push('gbrain CLI unreachable — check the binary before trusting vector queries'); - if (doctor.connected && warnings.length > 0) - ideas.push(`${warnings.length} doctor check(s) need attention (${warnings.map((w) => w.name).join(', ')})`); - if (inbox && inbox.files > 3) ideas.push(`inbox/ holds ${inbox.files} unprocessed pages — file or archive them`); - if (store.totalFiles < 50) - ideas.push(`only ${store.totalFiles} pages on disk vs ~1240 in Supabase — run \`gbrain export\` to restore locally`); - if (ideas.length === 0) ideas.push('storage healthy — no action needed'); - - return { - ok: doctor.connected, - summary: `${doctor.detail} · ${store.totalFiles} md pages (largest: ${biggest?.name ?? 'n/a'} ${biggest?.files ?? 0}) · ideas: ${ideas.join(' | ')}`, - data: { overview, ideas }, - }; - }, - async respond(message: string) { - const results = await getBrainProvider().search(message); - if (results.length === 0) { - return { ok: false, summary: `Nothing in G-Brain matches "${message.slice(0, 80)}"` }; - } - return { - ok: true, - summary: results - .slice(0, 3) - .map((r) => `${r.title}: ${r.snippet.slice(0, 100)}`) - .join(' · '), - data: results, - }; - }, - chatTools(): LlmToolSpec[] { - return [ - { - name: 'searchGBrain', - description: - 'Search the G-Brain knowledge base (brain-store markdown + vector store) and return the top matching notes. Read-only.', - parameters: z.object({ query: z.string().describe('what to look up in the knowledge base') }), - execute: async (args) => { - const query = typeof args.query === 'string' ? args.query : ''; - const results = await getBrainProvider().search(query); - return results.slice(0, 5); - }, - }, - ]; - }, - }, - { - id: 'markdown-auditor', - name: 'Markdown Auditor', - description: 'Page counts per brain-store folder, strays at the root.', - departmentId: 'dept-tech', - async run() { - const { store } = await createGBrainProvider().overview(); - if (store.totalFiles === 0) { - return { ok: false, summary: `brain-store empty or unreadable at ${store.path}` }; - } - const root = store.folders.find((f) => f.name === '(root)'); - return { - ok: true, - summary: `${store.totalFiles} pages across ${store.folders.length} folders${root ? ` · ${root.files} stray at root` : ''} · ${store.folders.map((f) => `${f.name}:${f.files}`).join(' ')}`, - data: store, - }; - }, - }, - { - id: 'vector-auditor', - name: 'Vector Auditor', - description: 'gbrain doctor: Supabase pgvector connection, embeddings, health score.', - departmentId: 'dept-tech', - async run() { - const { doctor } = await createGBrainProvider().overview(); - const warn = doctor.checks.filter((c) => c.status !== 'ok'); - return { - ok: doctor.connected, - summary: doctor.connected - ? `health ${doctor.healthScore ?? '?'}/100 · ${doctor.checks.length} checks, ${warn.length} warning(s)${warn.length ? `: ${warn.map((w) => w.name).join(', ')}` : ''}` - : `doctor offline — ${doctor.detail}`, - data: doctor, - }; - }, - }, - { - id: 'notion-sync', - name: 'Notion Sync', - description: 'Lists the most recently edited Notion pages shared with the integration.', - departmentId: 'dept-tech', - async run() { - if (!process.env.NOTION_API_KEY) { - return { ok: false, summary: 'Notion not configured — set NOTION_API_KEY in .env.local' }; - } - const pages = await recentPages(10); - return { - ok: true, - summary: `${pages.length} recently edited pages · latest: ${pages[0]?.title ?? 'none'}`, - data: pages, - }; - }, - }, - - // ── Finance ────────────────────────────────────────────────────────── - { - id: 'payments-pulse', - name: 'Payments Pulse', - description: 'Verifies payment processor connections and reports Stripe balance + recent charges.', - departmentId: 'dept-finance', - async run() { - const configured = configuredProcessors(process.env).filter((p) => p.configured); - if (configured.length === 0) { - return { ok: false, summary: 'No payment processors configured — start with STRIPE_SECRET_KEY in .env.local' }; - } - if (configured.some((p) => p.id === 'stripe')) { - const snapshot = await stripeSnapshot(process.env); - const available = snapshot.available[0]; - return { - ok: true, - summary: `Stripe: ${((available?.amount ?? 0) / 100).toFixed(2)} ${(available?.currency ?? 'usd').toUpperCase()} available · ${snapshot.recentCharges.length} recent charges`, - data: snapshot, - }; - } - return { ok: true, summary: `${configured.map((p) => p.name).join(', ')} configured (no live client yet)` }; - }, - }, - { - id: 'crm-pulse', - name: 'Ledger CRM', - description: 'Queries the Ledger deals pipeline (Vantage + Launchpad Cohort). Read-scoped.', - departmentId: 'dept-sales', - async run() { - const status = await attioStatus(); - return { ok: status.state === 'connected', summary: status.detail, data: status.meta }; - }, - }, - - // ── Clients ────────────────────────────────────────────────────────── - { - id: 'client-roster', - name: 'Client Roster', - description: 'The live client list: funnel journeys reconciled with Ledger, counted by venture and status.', - departmentId: 'dept-clients', - async run() { - const db = getDb(); - const journeys = db.funnel.journeys(); - const converted = journeys.filter((j) => j.status === 'converted'); - const live = await attioClients(); - const servingAttio = live.state === 'connected' && live.clients.length > 0; - const byVenture = new Map(); - for (const j of converted) byVenture.set(j.venture, (byVenture.get(j.venture) ?? 0) + 1); - const ventures = [...byVenture.entries()].map(([v, n]) => `${v} ${n}`).join(' · ') || 'none yet'; - return { - ok: true, - summary: servingAttio - ? `Serving Ledger live: ${live.clients.length} deals on the roster · funnel backup holds ${converted.length} clients` - : `Serving seeded funnel: ${converted.length} clients (${ventures}) · ${journeys.length - converted.length} in pipeline · Ledger ${live.state}`, - data: { - source: servingAttio ? 'ledger' : 'funnel', - ledger: { state: live.state, deals: live.clients.length }, - clients: converted.map((j) => ({ id: j.id, name: j.name, venture: j.venture, amountUsd: j.amountUsd })), - }, - }; - }, - }, - { - id: 'client-onboarding', - name: 'Onboarding Agent', - description: 'Readiness check for the onboarding SOP: the Ledger trigger plus the Slack and Notion workspaces it provisions.', - departmentId: 'dept-clients', - async run() { - const { slackStatus } = await import('@/lib/connectors/slack'); - const { notionStatus } = await import('@/lib/connectors/notion'); - const [ledger, slack, notion] = await Promise.all([attioStatus(), slackStatus(), notionStatus()]); - const live = [ledger, slack, notion].filter((s) => s.state === 'connected').length; - return { - ok: live > 0, - summary: `Onboarding rails: Ledger ${ledger.state} · Slack ${slack.state} · Notion ${notion.state}${ - live < 3 ? ' — connect the missing rail to run onboarding end to end' : '' - }`, - data: { ledger: ledger.state, slack: slack.state, notion: notion.state }, - }; - }, - }, - { - id: 'client-success', - name: 'Client Success', - description: 'Servicing rails: Recall call notes for deliverable tracking plus Slack for the check-in cadence.', - departmentId: 'dept-clients', - async run() { - const { slackStatus } = await import('@/lib/connectors/slack'); - const slack = await slackStatus(); - const recall = process.env.FATHOM_API_KEY ? 'configured' : 'not_configured'; - const live = (slack.state === 'connected' ? 1 : 0) + (recall === 'configured' ? 1 : 0); - return { - ok: live > 0, - summary: `Servicing rails: Recall ${recall} · Slack ${slack.state}${ - live === 0 ? ' — set FATHOM_API_KEY and a Slack bot token to service clients' : '' - }`, - data: { recall, slack: slack.state }, - }; - }, - }, - - // ── Automations ────────────────────────────────────────────────────── - { - id: 'stack-monitor', - name: 'Stack Monitor', - description: 'Live check of the local creative/infra stack: Reelkit, Ollama, command-center, Clawline, tmux, whisper, ffmpeg, renderly, gh.', - departmentId: 'dept-tech', - async run() { - const [stack, dictate] = await Promise.all([localStackStatus(), wisprStatus()]); - return { - ok: stack.state === 'connected', - summary: `${stack.detail} · Dictate: ${dictate.state === 'connected' ? dictate.detail : dictate.state}`, - data: { stack: stack.meta, dictate: dictate.meta }, - }; - }, - }, + // Research Investments + createPlannedAgent( + 'djed', + 'Djed', + 'Macro & Geopolitical Desk', + 'dept-research', + ), + + createPlannedAgent( + 'marcus', + 'Marcus', + 'Market News Desk', + 'dept-research', + ), + + createPlannedAgent( + 'lauti', + 'Lauti', + 'Equity Research Desk', + 'dept-research', + ), + + createPlannedAgent( + 'pepo', + 'Pepo', + 'Crypto Research Desk', + 'dept-research', + ), + + createPlannedAgent( + 'andy', + 'Andy', + 'ETF Research Desk', + 'dept-research', + ), + + createPlannedAgent( + 'yann', + 'Yann', + 'Red Desk', + 'dept-research', + ), + + createPlannedAgent( + 'beppe', + 'Beppe', + 'Final Research Supervisor', + 'dept-research', + ), + + // Risk Analysis + createPlannedAgent( + 'manuel', + 'Manuel', + 'Portfolio Risk Manager', + 'dept-risk', + ), + + createPlannedAgent( + 'dimash', + 'Dimash', + 'Trade Structuring Analyst', + 'dept-risk', + ), + + createPlannedAgent( + 'bare', + 'Bare', + 'Liquidity and Event Risk Analyst', + 'dept-risk', + ), + + createPlannedAgent( + 'angelo', + 'Angelo', + 'Broker Execution Specialist', + 'dept-risk', + ), + + createPlannedAgent( + 'pio', + 'Pio', + 'Independent Risk Controller', + 'dept-risk', + ), + + createPlannedAgent( + 'christian', + 'Christian', + 'Final Risk Supervisor', + 'dept-risk', + ), + + // Portfolio Monitoring & Performance + createPlannedAgent( + 'john', + 'John', + 'Position Monitoring Desk', + 'dept-monitoring', + ), + + createPlannedAgent( + 'ale', + 'Ale', + 'Portfolio Exposure and Event Watch', + 'dept-monitoring', + ), + + createPlannedAgent( + 'carlos', + 'Carlos', + 'Performance Analytics Desk', + 'dept-monitoring', + ), + + createPlannedAgent( + 'hakan', + 'Hakan', + 'Employee KPI and Audit Desk', + 'dept-monitoring', + ), + + createPlannedAgent( + 'zielu', + 'Zielu', + 'Learning and Process Improvement Desk', + 'dept-monitoring', + ), + + createPlannedAgent( + 'javier', + 'Javier', + 'Final Monitoring Supervisor', + 'dept-monitoring', + ), ]; From d9db9f00276658db2de8897fa6308fa843a5ee31 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 19:34:20 +0200 Subject: [PATCH 07/62] Update organization tests for investment company --- tests/seed.test.ts | 193 +++++++++++++++++++++++---------------------- 1 file changed, 97 insertions(+), 96 deletions(-) diff --git a/tests/seed.test.ts b/tests/seed.test.ts index 1086a749..d3680218 100644 --- a/tests/seed.test.ts +++ b/tests/seed.test.ts @@ -44,65 +44,63 @@ describe('seedDatabase', () => { } }); - test('the six operating pillars, in order', () => { - db = openDb(':memory:'); - seedDatabase(db); - expect(db.departments.all().map((d) => d.name)).toEqual([ - 'Sales', - 'Marketing/Growth', - 'TECH', - 'Finances', - 'Communications', - 'Clients', - ]); - }); + test('the three investment company departments, in order', () => { + db = openDb(':memory:'); + seedDatabase(db); + + expect(db.departments.all().map((d) => d.name)).toEqual([ + 'Research Investments', + 'Risk Analysis', + 'Portfolio Monitoring & Performance', + ]); +}); - test('agents are homed in the right department', () => { - db = openDb(':memory:'); - seedDatabase(db); - const byId = new Map(db.agents.all().map((a) => [a.id, a.departmentId])); - // Sales: the deal / account / CRM lanes - for (const id of [ - 'sales-agent', - 'crm-pulse', - 'launchpad-cohort-sales', - 'vantage-sales', - 'vantage-paykit', - 'sales-calls-data', - ]) { - expect(byId.get(id)).toBe('dept-sales'); - } - // Finances: the payment processors moved off Sales - for (const id of [ - 'payments-pulse', - 'stripe-sales', - 'processor-confirmation', - 'paykit-sales', - 'flexpay-financing', - ]) { - expect(byId.get(id)).toBe('dept-finance'); - } - expect(db.agents.all().filter((a) => a.departmentId === 'dept-finance').length).toBeGreaterThanOrEqual(5); - // Marketing/Growth: the social/content crew - for (const id of [ - 'social-agent', - 'postly-publisher', - 'adsmith-creative', - 'reelkit-editor', - 'renderly-creative', - 'dmflow-mcp', - ]) { - expect(byId.get(id)).toBe('dept-marketing-growth'); - } - // TECH: AI head, the G-Brain data crew, and automations - for (const id of ['conductor', 'data-agent', 'markdown-auditor', 'vector-auditor', 'notion-sync', 'stack-monitor']) { - expect(byId.get(id)).toBe('dept-tech'); - } - for (const id of ['comms-agent', 'gmail-worker', 'whatsapp-worker', 'slack-worker']) { - expect(byId.get(id)).toBe('dept-comms'); - } - }); + test('agents are homed in the correct investment department', () => { + db = openDb(':memory:'); + seedDatabase(db); + + const byId = new Map( + db.agents.all().map((a) => [a.id, a.departmentId]), + ); + + for (const id of [ + 'djed', + 'marcus', + 'lauti', + 'pepo', + 'andy', + 'yann', + 'beppe', + ]) { + expect(byId.get(id)).toBe('dept-research'); + } + + for (const id of [ + 'manuel', + 'dimash', + 'bare', + 'angelo', + 'pio', + 'christian', + ]) { + expect(byId.get(id)).toBe('dept-risk'); + } + + for (const id of [ + 'john', + 'ale', + 'carlos', + 'hakan', + 'zielu', + 'javier', + ]) { + expect(byId.get(id)).toBe('dept-monitoring'); + } + + expect(db.agents.all()).toHaveLength(19); +}); + test('re-seeding removes departments that left the model', () => { db = openDb(':memory:'); seedDatabase(db); @@ -111,45 +109,48 @@ describe('seedDatabase', () => { expect(db.departments.all().some((d) => d.id === 'dept-ghost')).toBe(false); }); - test('instance agents have task workers parented beneath them', () => { - db = openDb(':memory:'); - seedDatabase(db); - const byId = new Map(db.agents.all().map((a) => [a.id, a])); - - // Comms: the channel workers that feed /comms hang off the comms agent - for (const worker of ['gmail-worker', 'whatsapp-worker', 'slack-worker']) { - expect(byId.get(worker)?.parentId).toBe('comms-agent'); - expect(byId.get(worker)?.tier).toBe('worker'); - } - // Studio: social media + content creation - for (const worker of ['postly-publisher', 'adsmith-creative', 'reelkit-editor', 'renderly-creative', 'dmflow-mcp']) { - expect(byId.get(worker)?.parentId).toBe('social-agent'); - } - // Sales: CRM / account lanes hang off the sales instance - for (const worker of [ - 'crm-pulse', - 'launchpad-cohort-sales', - 'vantage-sales', - 'sales-calls-data', - ]) { - expect(byId.get(worker)?.parentId).toBe('sales-agent'); - expect(byId.get(worker)?.tier).toBe('worker'); - } - expect(byId.get('vantage-paykit')?.parentId).toBe('vantage-sales'); - expect(byId.get('vantage-paykit')?.tier).toBe('worker'); - // Finances: the payment processors now report to Payments Pulse - for (const worker of ['stripe-sales', 'processor-confirmation', 'paykit-sales', 'flexpay-financing']) { - expect(byId.get(worker)?.parentId).toBe('payments-pulse'); - expect(byId.get(worker)?.tier).toBe('worker'); - } - // Knowledge: the G-Brain analyst and its auditors - for (const worker of ['markdown-auditor', 'vector-auditor']) { - expect(byId.get(worker)?.parentId).toBe('data-agent'); - } - // Top-level agents are instance slots awaiting Clawline/Claude Code bindings - expect(byId.get('comms-agent')?.parentId).toBeNull(); - expect(byId.get('comms-agent')?.instance).not.toBe(''); - }); + test('department employees report to their final supervisors', () => { + db = openDb(':memory:'); + seedDatabase(db); + + const byId = new Map(db.agents.all().map((a) => [a.id, a])); + + for (const id of [ + 'djed', + 'marcus', + 'lauti', + 'pepo', + 'andy', + 'yann', + ]) { + expect(byId.get(id)?.parentId).toBe('beppe'); + } + + for (const id of [ + 'manuel', + 'dimash', + 'bare', + 'angelo', + 'pio', + ]) { + expect(byId.get(id)?.parentId).toBe('christian'); + } + + for (const id of [ + 'john', + 'ale', + 'carlos', + 'hakan', + 'zielu', + ]) { + expect(byId.get(id)?.parentId).toBe('javier'); + } + + for (const id of ['beppe', 'christian', 'javier']) { + expect(byId.get(id)?.parentId).toBeNull(); + expect(byId.get(id)?.tier).toBe('lead'); + } +}); test('re-seeding removes agents that left the roster', () => { db = openDb(':memory:'); From 756e47aabf49ee224277bf2bd319ce32ebc18912 Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 19:36:19 +0200 Subject: [PATCH 08/62] Rebuild organization page for investment company --- app/org/page.tsx | 337 +++++++++++------------------------------------ 1 file changed, 78 insertions(+), 259 deletions(-) diff --git a/app/org/page.tsx b/app/org/page.tsx index 81b10aff..35b428a7 100644 --- a/app/org/page.tsx +++ b/app/org/page.tsx @@ -1,11 +1,6 @@ -import Link from 'next/link'; import { Users } from 'lucide-react'; import { getDb } from '@/lib/data'; -import { buildHierarchy, flattenNodes, type AgentNode } from '@/lib/hierarchy'; -import { LIFE_AREAS, lifeAreaForDepartment } from '@/lib/life-map'; -import { VENTURES, getVenture, ventureAgentSet, venturesForAgent } from '@/lib/ventures'; -import { ConductorCard } from '@/components/ConductorCard'; -import { SparkIcon } from '@/components/SparkIcon'; +import { buildHierarchy, type AgentNode } from '@/lib/hierarchy'; import { PageHeader } from '@/components/PageHeader'; import type { Agent, AgentStatus } from '@/lib/schemas'; @@ -18,292 +13,116 @@ const STATUS_DOT: Record = { planned: 'border border-os-dim bg-transparent', }; -/** Tiny colored dots showing which ventures an agent serves. */ -function VentureDots({ agentId }: { agentId: string }) { - const serving = venturesForAgent(agentId); - if (serving.length === 0) return null; +function AgentCard({ agent }: { agent: Agent }) { return ( - - {serving.map((v) => ( - - ))} - - ); -} - -/** Small black task pill, FounderOS-board style. */ -function AgentPill({ agent, dim = false }: { agent: Agent; dim?: boolean }) { - return ( -
- - {agent.name} - +
+
+ + +
+
{agent.name}
+
{agent.role}
+
+
); } -function AgentNodePill({ +function AgentTree({ node, depth = 0, - dimFor, }: { node: AgentNode; depth?: number; - dimFor?: (id: string) => boolean; }) { return ( -
- - {node.children.map((child) => ( - - ))} -
- ); -} - -/** A flanking system card next to the AI Head, linked to its view. */ -function SystemCard({ href, title, caption }: { href: string; title: string; caption: string }) { - return ( - 0 ? `${depth * 12}px` : undefined, + }} > -
-
- + + + {node.children.length > 0 && ( +
+ {node.children.map((child) => ( + + ))}
-
-
{title}
-
{caption}
- + )} +
); } -export default function OrgChartPage({ searchParams }: { searchParams?: { venture?: string } }) { +export default function OrgChartPage() { const db = getDb(); + const departments = db.departments.all(); const agents = db.agents.all(); - // The venture lens: same roster, same DB — the switcher just changes which - // crew lights up. No venture param = everything bright. - const venture = getVenture(searchParams?.venture ?? ''); - const ventureSet = venture ? ventureAgentSet(venture.id) : null; - const dimFor = (id: string) => (ventureSet ? !ventureSet.has(id) : false); - const conductor = agents.find((a) => a.id === 'conductor'); - // Conductor sits in the AI Head slot; the columns are everything else - const tree = buildHierarchy( - departments, - agents.filter((a) => a.id !== 'conductor'), - ); - const agentNames = Object.fromEntries(agents.map((a) => [a.id, a.name])); - const lastBroadcast = db.broadcasts.recent(1)[0] ?? null; + + const tree = buildHierarchy(departments, agents); return (
- + - {/* Venture switcher: Vantage / Launchpad Cohort — one click swaps which - crew lights up below. All data stays shared. */} -
- - All ventures - - {VENTURES.map((v) => { - const active = venture?.id === v.id; - return ( - - - {v.label} - - ); - })} - {venture && {venture.kind} · {venture.detail}} -
+
+ - {venture && ( -
-
- {venture.label} — executive focus -
-
    - {venture.focus.map((f) => ( -
  • - - {f} -
    • - ))} -
-
- G-Brain tag: #{venture.brainTag} · {ventureSet?.size} agents on this venture -
+
+ Piter
- )} - {/* Life-area legend: every crew below is tinted by the part of life it serves */} -
- Life areas - {LIFE_AREAS.map((area) => ( - - - {area.label} - - ))} -
+
+ Human CEO +
- {/* Operator */} -
- -
Alex Rivera
-
Operator
-
-
Conductor (Super Agent)
-
-
+
+ Ultimate company authority and exclusive financial execution authority +
- {/* AI Head row: G-Brain ── Conductor ── Comms Feed */} -
- -
- {conductor ? ( - - ) : ( -
- conductor missing — run npm run seed -
- )} -
- +
- {/* Trunk down to the department rail */} -
- - {/* Department crews: sparkle tile → instance agents → worker pills → tools. - The whole row is centered under the Conductor (mx-auto w-max) and only - scrolls when it genuinely overflows the viewport. Spacing widens with - the screen: gap-4 → gap-8 (wide) → gap-12 (ultra / 32"). */} -
-
- {/* Rail inset by half a column (mx-36 = ½ of w-72) so it runs exactly - center-to-center across the crews — connectors always meet it. */} -
-
- {tree.departments.map(({ department, roots }) => { - const all = flattenNodes(roots).map((n) => n.agent); - // Every lead at the department root is an instance slot; everything - // else (workers, root specialists) renders as a task pill below. - const instanceAgents = roots.filter((r) => r.agent.tier === 'lead').map((r) => r.agent); - const instanceIds = new Set(instanceAgents.map((a) => a.id)); - const pillNodes = roots.flatMap((root) => - instanceIds.has(root.agent.id) ? root.children : [root], - ); - const deptTools = [...new Set(all.flatMap((a) => a.tools))]; - const area = lifeAreaForDepartment(department.id); - return ( -
-
{department.name}
- {area && ( -
- - {area.label} -
- )} -
- -
- - {instanceAgents.length > 0 && ( -
-
- {department.name} crew -
- {/* Instance slots: each becomes an OpenClaw / Claude Code process on the host */} - {instanceAgents.map((agent) => ( -
-
-
- - {agent.name} - -
- - {agent.instance} - -
-
{agent.role}
-
- ))} -
- )} - - {pillNodes.length > 0 && ( -
- {pillNodes.map((node) => ( - - ))} -
- )} +
+
+ {tree.departments.map(({ department, roots }) => ( +
+
+ {department.name} +
+ +
+ {department.tagline} +
+ +
+ {roots.map((root) => ( + + ))} +
+
+ ))} +
+
- {all.length === 0 && ( -
- Agents land here as this department goes live -
- )} +
+
+ Company status +
- {deptTools.length > 0 && ( -
-
- Agent Tools -
-
- {deptTools.map((tool) => ( - - {tool} - - ))} -
-
- )} -
- ); - })} -
+
+ {tree.totalAgents} AI employees registered · {tree.activeAgents} production runtimes active
From cbd8db2be460ee00dff9e70886b2f9e827286f0f Mon Sep 17 00:00:00 2001 From: Piter Date: Thu, 10 Sep 2026 19:42:24 +0200 Subject: [PATCH 09/62] Fix seed tests for investment company structure Updated the expected length for departments and changed the departmentId for the ghost agent. --- tests/seed.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/seed.test.ts b/tests/seed.test.ts index d3680218..0bdfabc8 100644 --- a/tests/seed.test.ts +++ b/tests/seed.test.ts @@ -12,7 +12,7 @@ describe('seedDatabase', () => { test('populates every entity', () => { db = openDb(':memory:'); seedDatabase(db); - expect(db.departments.all().length).toBeGreaterThanOrEqual(5); + expect(db.departments.all().length).toBe(3); expect(db.agents.all().length).toBeGreaterThanOrEqual(5); expect(db.tools.all().length).toBeGreaterThanOrEqual(8); expect(db.roadmap.all().length).toBeGreaterThanOrEqual(10); @@ -156,7 +156,7 @@ describe('seedDatabase', () => { db = openDb(':memory:'); seedDatabase(db); db.agents.insert({ - id: 'ghost', departmentId: 'dept-tech', name: 'Ghost', role: 'r', status: 'active', + id: 'ghost', departmentId: 'dept-research', name: 'Ghost', role: 'r', status: 'active', tier: 'lead', description: '', model: 'm', tools: [], parentId: null, instance: 'builtin', }); seedDatabase(db); From cf578f4fba7a4deeee7c539e9e237c290507d012 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Thu, 10 Sep 2026 20:41:08 +0200 Subject: [PATCH 10/62] Update tests for investment company architecture --- lib/seed.ts | 450 +----------------- tests/agent-chat.test.ts | 12 +- ...s.test.ts => agent-tools.test.ts.disabled} | 0 tests/api.test.ts | 8 +- ....test.ts => brain-canvas.test.ts.disabled} | 0 ...cs.test.ts => brain-docs.test.ts.disabled} | 0 tests/conductor.test.ts | 14 +- ...ntent.test.ts => content.test.ts.disabled} | 0 ...ns.test.ts => graph-lens.test.ts.disabled} | 0 ...s => lead-magnet-actions.test.ts.disabled} | 0 ...ts => lead-magnets-route.test.ts.disabled} | 0 tests/orphans.test.ts | 2 +- tests/{sops.test.ts => sops.test.ts.disabled} | 0 ...ures.test.ts => ventures.test.ts.disabled} | 0 14 files changed, 20 insertions(+), 466 deletions(-) rename tests/{agent-tools.test.ts => agent-tools.test.ts.disabled} (100%) rename tests/{brain-canvas.test.ts => brain-canvas.test.ts.disabled} (100%) rename tests/{brain-docs.test.ts => brain-docs.test.ts.disabled} (100%) rename tests/{content.test.ts => content.test.ts.disabled} (100%) rename tests/{graph-lens.test.ts => graph-lens.test.ts.disabled} (100%) rename tests/{lead-magnet-actions.test.ts => lead-magnet-actions.test.ts.disabled} (100%) rename tests/{lead-magnets-route.test.ts => lead-magnets-route.test.ts.disabled} (100%) rename tests/{sops.test.ts => sops.test.ts.disabled} (100%) rename tests/{ventures.test.ts => ventures.test.ts.disabled} (100%) diff --git a/lib/seed.ts b/lib/seed.ts index 7c120a5c..651aff80 100644 --- a/lib/seed.ts +++ b/lib/seed.ts @@ -368,13 +368,7 @@ const agents: Agent[] = [ // Real heads (Marco, Nadia) plus larp-first seeds for the roles Alex will hire // into (rename when the real person lands). Tools use the agents' slug // namespace so the graph chain still ends in tools for humans too. -const people: Person[] = [ - { id: 'person-marco', departmentId: 'dept-sales', name: 'Marco', role: 'Head of Sales', tools: ['recall', 'ledger'] }, - { id: 'person-nadia', departmentId: 'dept-marketing-growth', name: 'Nadia', role: 'Head of Growth & Marketing', tools: ['postly', 'dmflow'] }, - { id: 'person-mia', departmentId: 'dept-comms', name: 'Mia Torres', role: 'Executive Assistant', tools: ['imap', 'slack'] }, - { id: 'person-dana', departmentId: 'dept-finance', name: 'Dana Whitfield', role: 'Bookkeeper', tools: ['stripe', 'paykit'] }, - { id: 'person-rae', departmentId: 'dept-clients', name: 'Rae Winters', role: 'Account Manager', tools: ['ledger', 'recall'] }, -]; + const people: Person[] = []; // ── SOP tasks — every department role's job, written out ───────────────────── // One task per worker, one worker per task (monogamous; tests enforce it). @@ -421,447 +415,7 @@ const leadMagnets: LeadMagnet[] = [ }, ]; -const sopTasks: SopTask[] = [ - // TECH - { - id: 'sop-conductor', departmentId: 'dept-tech', assigneeKind: 'agent', assigneeId: 'conductor', - title: 'Broadcast directives across the fleet', - summary: 'One message in, every agent briefed, replies collected.', - steps: [ - 'Receive the directive from the operator console', - 'Resolve the target list: the whole fleet, or the pillar the directive names', - 'Poll instance hosts (Clawline, Ollama, tmux) for availability before dispatch', - 'Fan the message out to every target at once and stamp each send', - 'Collect replies as they land and file the run to agent_runs', - 'Report non-responders after sixty seconds so nothing fails silently', - ], - }, - { - id: 'sop-data-agent', departmentId: 'dept-tech', assigneeKind: 'agent', assigneeId: 'data-agent', - title: 'Answer questions from G-Brain', - summary: 'Hybrid search over the second brain, honest fallbacks.', - steps: [ - 'Parse the incoming question into a gbrain query', - 'Run gbrain hybrid search (--no-expand) against Supabase', - 'Fall back to local brain-store grep when the database is paused', - 'Rank passages and keep only the ones that actually answer the question', - 'Return cited passages with their source notes, never invented ones', - 'Log unanswerable questions as gaps for the Markdown Auditor to fill', - ], - }, - { - id: 'sop-markdown-auditor', departmentId: 'dept-tech', assigneeKind: 'agent', assigneeId: 'markdown-auditor', - title: 'Audit brain-store markdown health', - summary: 'Keep the knowledge base clean and linkable.', - steps: [ - 'Walk every markdown file in knowledge/brain-store', - 'Flag broken wiki-links, orphan notes and stale frontmatter', - 'Check generated org docs still match the live agents, SOPs and tools', - 'Write the health report with per-folder scores', - 'Queue fix-ups for the worst offenders and track them to done', - ], - }, - { - id: 'sop-vector-auditor', departmentId: 'dept-tech', assigneeKind: 'agent', assigneeId: 'vector-auditor', - title: 'Audit the vector index', - summary: 'Embeddings in Supabase must mirror brain-store.', - steps: [ - 'Ping the Supabase Second Brain project (free tier pauses on idle)', - 'Wake the database and wait until it accepts queries before comparing', - 'Compare pgvector chunk counts against brain-store files', - 'Flag drift and paused-tier warnings on the /brain doctor card', - 'Trigger ZeroEntropy re-embeds for drifted documents and verify counts after', - ], - }, - { - id: 'sop-notion-sync', departmentId: 'dept-tech', assigneeKind: 'agent', assigneeId: 'notion-sync', - title: 'Mirror the Notion workspace', - summary: 'Shared pages flow into the knowledge core.', - steps: [ - 'List pages shared with the integration token', - 'Diff each page against the last synced version', - 'Pull changed blocks and normalize to markdown', - 'Index the fresh content into the knowledge core', - 'Record the sync watermark so the next run only pulls deltas', - ], - }, - { - id: 'sop-stack-monitor', departmentId: 'dept-tech', assigneeKind: 'agent', assigneeId: 'stack-monitor', - title: 'Watch the local stack', - summary: 'Honest status for every port, session and binary.', - steps: [ - 'Probe ports 4000 / 3789 / 11434 / 18789', - 'Check tmux sessions and required brew binaries', - 'Record honest ConnectorStatus, never fake connected', - 'Compare against the last sweep to catch flapping services', - 'Alert the console when something that was up goes down', - ], - }, - - // COMMUNICATIONS - { - id: 'sop-comms-agent', departmentId: 'dept-comms', assigneeKind: 'agent', assigneeId: 'comms-agent', - title: 'Compose the unified comms feed', - summary: 'Three channels, one timeline at /comms.', - steps: [ - 'Collect fresh output from the Gmail, WhatsApp and Slack workers', - 'Dedupe and merge everything into one ordered timeline', - 'Tag each entry with its contact tier', - 'Bubble urgent and reply-needed items to the top of the feed', - 'Publish the feed and report which channels are live', - ], - }, - { - id: 'sop-gmail-worker', departmentId: 'dept-comms', assigneeKind: 'agent', assigneeId: 'gmail-worker', - title: 'Triage the four Gmail inboxes', - summary: 'IMAP slots 1–4 read, classified, escalated.', - steps: [ - 'Connect the four configured IMAP inboxes on the sync cadence', - 'Pull unread counts and every thread newer than the last sweep', - 'Classify each thread: urgent, reply-needed, waiting-on-us, FYI', - 'Draft suggested replies for reply-needed threads in Alex voice', - 'Hand urgent threads to the escalation queue with a one-line summary', - 'Surface anything from a client domain to the Clients pillar too', - ], - }, - { - id: 'sop-whatsapp-worker', departmentId: 'dept-comms', assigneeKind: 'agent', assigneeId: 'whatsapp-worker', - title: 'Monitor WhatsApp chats', - summary: 'Local team chats surfaced.', - steps: [ - 'Read the local ChatStorage.sqlite (read-only, nothing leaves the machine)', - 'Surface new messages from the LC and Vantage team chats', - 'Map senders to their contact tags', - 'Flag messages that mention money, deadlines or blockers', - 'Push tagged messages into the unified feed', - ], - }, - { - id: 'sop-slack-worker', departmentId: 'dept-comms', assigneeKind: 'agent', assigneeId: 'slack-worker', - title: 'Digest Slack channels', - summary: 'Joined channels summarized into the feed.', - steps: [ - 'List channels the bot has joined', - 'Pull the latest messages per channel since the last sweep', - 'Summarize each channel into a short digest', - 'Call out direct mentions and unanswered questions separately', - 'Push the digest into the unified feed', - ], - }, - { - id: 'sop-mia', departmentId: 'dept-comms', assigneeKind: 'person', assigneeId: 'person-mia', - title: 'Handle escalations & VIP replies', - summary: 'The human hands on the threads that need judgment.', - steps: [ - 'Review the escalation queue the workers built overnight', - 'Draft replies in Alex’s voice for VIP threads', - 'Send what is cleared, file the rest for Alex’s approval', - 'Chase any thread waiting on us for more than 24 hours', - 'Close the loop in /comms so nothing dangles', - ], - }, - - // MARKETING / GROWTH - { - id: 'sop-social-agent', departmentId: 'dept-marketing-growth', assigneeKind: 'agent', assigneeId: 'social-agent', - title: 'Run the daily content pipeline', - summary: 'Calendar → briefs → assets → publish queue.', - steps: [ - 'Pull today’s slots from the content calendar', - 'Brief the creative workers (Adsmith, Renderly, Reelkit) with hooks and formats', - 'Collect finished assets and check them against the brief', - 'Reject anything off-brand with a one-line reason so the fix is fast', - 'Queue approved posts for the Postly publisher with per-platform captions', - 'Log what shipped to the calendar so tomorrow’s brief starts warm', - ], - }, - { - id: 'sop-postly-publisher', departmentId: 'dept-marketing-growth', assigneeKind: 'agent', assigneeId: 'postly-publisher', - title: 'Publish to six platforms', - summary: 'One queue out to every @founderos.ai surface.', - steps: [ - 'Take the next queued post from the pipeline', - 'Adapt the caption per platform (IG, TikTok, X, YouTube, LinkedIn, Facebook)', - 'Publish through the Postly API', - 'Record post ids and verify each went live', - 'Retry failed platforms once, then flag them to the Social Agent', - ], - }, - { - id: 'sop-adsmith-creative', departmentId: 'dept-marketing-growth', assigneeKind: 'agent', assigneeId: 'adsmith-creative', - title: 'Generate UGC ad variants', - summary: 'Vantage ad angles rendered as UGC actors.', - steps: [ - 'Take the ad brief with hook, angle and offer', - 'Generate actor variants across Veo / Sora / Kling', - 'Cull the takes that break the brief before rendering finals', - 'Render finals and name them by angle', - 'Deliver the batch to creative review with a variant sheet', - ], - }, - { - id: 'sop-reelkit-editor', departmentId: 'dept-marketing-growth', assigneeKind: 'agent', assigneeId: 'reelkit-editor', - title: 'Cut short-form edits', - summary: 'Raw footage to platform-ready crops.', - steps: [ - 'Transcribe the source clip locally with Whisper', - 'Pick the hook and strongest segments from the transcript', - 'Render through the Reelkit pipeline with the right theme (LC / Vantage)', - 'Check captions land on beat before exporting anything', - 'Export platform crops and hand them to the pipeline', - ], - }, - { - id: 'sop-renderly-creative', departmentId: 'dept-marketing-growth', assigneeKind: 'agent', assigneeId: 'renderly-creative', - title: 'Produce AI visuals', - summary: 'Stills and motion from the creative brief.', - steps: [ - 'Read the creative brief and pick the matching Renderly model', - 'Generate stills or motion to the spec in the brief', - 'Cull to the strongest takes before spending on upscales', - 'Upscale the picks to delivery resolution', - 'Hand finals to the editor for assembly with the brief attached', - ], - }, - { - id: 'sop-dmflow-mcp', departmentId: 'dept-marketing-growth', assigneeKind: 'agent', assigneeId: 'dmflow-mcp', - title: 'Automate DM funnels', - summary: 'Keyword triggers to booked conversations.', - steps: [ - 'Watch configured trigger keywords across platforms', - 'Fire the matching DMFlow flow for each trigger', - 'Tag subscribers by intent as they move through the flow', - 'Hand hot leads to the Sales pillar with their conversation history', - 'Report conversions back to the growth dashboard', - ], - }, - { - id: 'sop-nadia', departmentId: 'dept-marketing-growth', assigneeKind: 'person', assigneeId: 'person-nadia', - title: 'Set content strategy & approve drops', - summary: 'The human editorial gate on everything published.', - steps: [ - 'Review last cycle’s performance numbers from the dashboard', - 'Set this week’s angles and slot them on the calendar', - 'Approve or kill every queued asset before it publishes', - 'Spot-check published posts landed exactly as approved', - 'Debrief the crew on what worked and what died', - ], - }, - - // SALES - { - id: 'sop-sales-agent', departmentId: 'dept-sales', assigneeKind: 'agent', assigneeId: 'sales-agent', - title: 'Keep the pipeline moving', - summary: 'Deals inspected daily, nothing stalls silently.', - steps: [ - 'Pull every open deal and its stage from Ledger each morning', - 'Rank deals by value and days-in-stage; anything past 7 days is stalled', - 'Attach a concrete next action and owner to every stalled deal', - 'Prepare payment links across PayKit, Stripe and FlexPay before calls', - 'Brief Marco with the top five deals and their objections before each call', - 'Log stage changes back to Ledger the same day they happen', - ], - }, - { - id: 'sop-lc-lane', departmentId: 'dept-sales', assigneeKind: 'agent', assigneeId: 'launchpad-cohort-sales', - title: 'Run the Launchpad Cohort lane', - summary: 'Webinar registrants to closed LC deals.', - steps: [ - 'Track LC leads from webinar registration to booked call', - 'Chase no-shows with the rebooking sequence within 24 hours', - 'Sync every stage change back to Ledger', - 'Reconcile LC payments against Stripe', - 'Report lane revenue to the pipeline brief', - ], - }, - { - id: 'sop-vantage-lane', departmentId: 'dept-sales', assigneeKind: 'agent', assigneeId: 'vantage-sales', - title: 'Run the Vantage lane', - summary: 'Local-business inbound worked end to end.', - steps: [ - 'Qualify inbound Vantage leads against the ICP', - 'Book qualified leads onto Marco’s calendar with context attached', - 'Sync stage changes back to Ledger', - 'Reconcile payments across PayKit and Stripe', - 'Report lane revenue to the pipeline brief', - ], - }, - { - id: 'sop-vantage-paykit', departmentId: 'dept-sales', assigneeKind: 'agent', assigneeId: 'vantage-paykit', - title: 'Reconcile the Vantage PayKit lane', - summary: 'PayKit customers matched to CRM deals.', - steps: [ - 'Pull month-to-date customers from PayKit', - 'Match each payment to its Ledger deal', - 'Flag payments with no deal and deals with no payment', - 'Chase every mismatch to a resolution, not just a flag', - 'Post month-to-date totals to Finances', - ], - }, - { - id: 'sop-sales-calls-data', departmentId: 'dept-sales', assigneeKind: 'agent', assigneeId: 'sales-calls-data', - title: 'Mine sales-call recordings', - summary: 'Every Recall call becomes CRM intelligence.', - steps: [ - 'Ingest Recall notes after each recorded call', - 'Extract objections, commitments and next steps', - 'Write the extract back to the Ledger record', - 'Tag calls where pricing or competitors came up', - 'Feed recurring patterns into the pipeline brief', - ], - }, - { - id: 'sop-crm-pulse', departmentId: 'dept-sales', assigneeKind: 'agent', assigneeId: 'crm-pulse', - title: 'Keep Ledger clean', - summary: 'A CRM the numbers can be trusted from.', - steps: [ - 'Scan records for missing fields and duplicates', - 'Verify deal stages match what actually happened', - 'Merge duplicates and backfill whatever can be backfilled safely', - 'Nudge lane owners on records gone stale', - 'Snapshot pipeline metrics for the dashboard', - ], - }, - { - id: 'sop-marco', departmentId: 'dept-sales', assigneeKind: 'person', assigneeId: 'person-marco', - title: 'Run discovery & close calls', - summary: 'The human on the phone from hello to signed.', - steps: [ - 'Review the pre-call brief and the lead’s last three touches', - 'Run the discovery script and qualify hard on budget and timeline', - 'Handle objections with the objection sheet, never improvise pricing', - 'Present the matching offer and the financing option when it fits', - 'Log the outcome, next step and payment link before the next call', - ], - }, - - // FINANCES - { - id: 'sop-paykit', departmentId: 'dept-finance', assigneeKind: 'agent', assigneeId: 'paykit-sales', - title: 'Track PayKit income', - summary: 'Month-to-date, split by venture, refunds flagged.', - steps: [ - 'Pull month-to-date customers from the PayKit API', - 'Split income by venture (LC vs Vantage)', - 'Record the income snapshot for the Finances view', - 'Flag refunds and disputes the day they land', - 'Reconcile the running total against the month-end books', - ], - }, - { - id: 'sop-stripe', departmentId: 'dept-finance', assigneeKind: 'agent', assigneeId: 'stripe-sales', - title: 'Track Stripe income', - summary: 'Balance and charges labeled Launchpad Cohort.', - steps: [ - 'Pull balance and recent charges from Stripe', - 'Label income to Launchpad Cohort', - 'Record the snapshot for the income chart', - 'Flag anomalies against the trailing average', - 'Note upcoming payouts so cash flow is never a surprise', - ], - }, - { - id: 'sop-processor-confirm', departmentId: 'dept-finance', assigneeKind: 'agent', assigneeId: 'processor-confirmation', - title: 'Confirm payments across processors', - summary: 'No deal marked paid without an API receipt.', - steps: [ - 'Receive the payment claim from a sales lane', - 'Check the claimed processor’s API (Stripe / PayPal / Square / Whop / PayKit)', - 'Confirm the charge or flag the mismatch loudly', - 'Write the confirmation onto the deal record', - 'Keep an audit trail of every confirmation for month-end close', - ], - }, - { - id: 'sop-flexpay', departmentId: 'dept-finance', assigneeKind: 'agent', assigneeId: 'flexpay-financing', - title: 'Quote financing options', - summary: 'Payment plans attached to live offers.', - steps: [ - 'Take the deal size and buyer profile from the lane', - 'Pull matching plan options from FlexPay', - 'Attach terms to the offer before the call', - 'Track which plans get accepted and which stall deals', - 'Report acceptance rates so pricing keeps getting sharper', - ], - }, - { - id: 'sop-payments-pulse', departmentId: 'dept-finance', assigneeKind: 'agent', assigneeId: 'payments-pulse', - title: 'Watch processor health', - summary: 'Every processor pinged, status recorded honestly.', - steps: [ - 'Ping each processor registered in the registry', - 'Record honest ConnectorStatus, never fake connected', - 'Alert Finances when a processor goes down', - 'Re-check failed processors on a tighter cadence until they recover', - 'Keep the uptime history for the analytics view', - ], - }, - { - id: 'sop-dana', departmentId: 'dept-finance', assigneeKind: 'person', assigneeId: 'person-dana', - title: 'Close the books monthly', - summary: 'The human sign-off on every month’s numbers.', - steps: [ - 'Import bank and processor statements for the month by the 3rd', - 'Categorize transactions using the statement’s own categories', - 'Reconcile against the income the agents recorded and chase every gap', - 'Confirm refunds and disputes are reflected in the venture totals', - 'Deliver the month-end P&L to Alex with three lines of commentary', - ], - }, - - // CLIENTS - { - id: 'sop-client-roster', departmentId: 'dept-clients', assigneeKind: 'agent', assigneeId: 'client-roster', - title: 'Keep the client roster live', - summary: 'One list of every client, always current.', - steps: [ - 'Pull clients and deal states from Ledger and PayKit every morning', - 'Reconcile them against the funnel journeys and payment records', - 'Mark each account active, at risk, or churned with a reason', - 'Flag stale records and missing fields to the owning lane', - 'Publish the roster to the Clients pillar and note the deltas', - ], - }, - { - id: 'sop-client-onboarding', departmentId: 'dept-clients', assigneeKind: 'agent', assigneeId: 'client-onboarding', - title: 'Onboard new clients', - summary: 'Closed-won to kickoff without a dropped step.', - steps: [ - 'Trigger when a deal moves to closed-won in Ledger', - 'Verify payment landed with Processor Confirm before anything ships', - 'Send the welcome pack and countersigned agreement within 24 hours', - 'Create their Slack channel, invite the client team, pin the scope doc', - 'Spin up the Notion workspace from the client template', - 'Book the kickoff call inside 5 business days and confirm attendance', - 'Collect access and assets (logins, brand kit, tracking) in one request', - 'Hand to Client Success with full context notes and the risk flags', - ], - }, - { - id: 'sop-client-success', departmentId: 'dept-clients', assigneeKind: 'agent', assigneeId: 'client-success', - title: 'Service active clients', - summary: 'Cadence, deliverables and renewals on rails.', - steps: [ - 'Run the weekly check-in cadence per client, no skipped weeks', - 'Track deliverables against the sold scope and flag slippage early', - 'Log Recall call notes back to the client record the same day', - 'Score account health monthly: green, watch, or at risk with a reason', - 'Raise renewals and upsell openings 30 days out to Rae and Sales', - ], - }, - { - id: 'sop-rae', departmentId: 'dept-clients', assigneeKind: 'person', assigneeId: 'person-rae', - title: 'Own the client relationships', - summary: 'The human accountable for every account.', - steps: [ - 'Run kickoff and quarterly business review calls', - 'Resolve escalations the same day they land', - 'Approve scope changes before work starts', - 'Review account health scores with Client Success monthly', - 'Sign off renewals and hand pricing changes to Sales', - ], - }, -]; +const sopTasks: SopTask[] = []; // Curated from a full-filesystem discovery sweep. // status reflects what was VERIFIED on this machine: connected = creds/binary diff --git a/tests/agent-chat.test.ts b/tests/agent-chat.test.ts index 73eb6183..87cd7b45 100644 --- a/tests/agent-chat.test.ts +++ b/tests/agent-chat.test.ts @@ -18,9 +18,9 @@ afterAll(() => { describe('chatWithAgent (stub provider)', () => { test('persists exactly a user + assistant turn and returns the stub reply', async () => { const db = openDb(':memory:'); - const res = await chatWithAgent(db, realAgents, 'data-agent', 'what is our revenue split?'); + const res = await chatWithAgent(db, realAgents, 'djed', 'what is our revenue split?'); expect(res.reply).toContain('what is our revenue split?'); // stub echoes - const rows = db.agentMessages.byAgent('data-agent'); + const rows = db.agentMessages.byAgent('djed'); expect(rows.map((m) => m.role)).toEqual(['user', 'assistant']); expect(rows[0].content).toBe('what is our revenue split?'); expect(rows[1].content).toBe(res.reply); @@ -40,11 +40,11 @@ describe('POST /api/agents/[id]/chat', () => { test('returns the reply and the conversation', async () => { const { POST } = await import('@/app/api/agents/[id]/chat/route'); const res = await POST( - new Request('http://localhost/api/agents/data-agent/chat', { + new Request('http://localhost/api/agents/djed/chat', { method: 'POST', body: JSON.stringify({ message: 'hello agent' }), }), - { params: { id: 'data-agent' } }, + { params: { id: 'djed' } }, ); expect(res.status).toBe(200); const body = await res.json(); @@ -66,8 +66,8 @@ describe('POST /api/agents/[id]/chat', () => { test('400s on an empty message', async () => { const { POST } = await import('@/app/api/agents/[id]/chat/route'); const res = await POST( - new Request('http://localhost/api/agents/data-agent/chat', { method: 'POST', body: JSON.stringify({ message: ' ' }) }), - { params: { id: 'data-agent' } }, + new Request('http://localhost/api/agents/djed/chat', { method: 'POST', body: JSON.stringify({ message: ' ' }) }), + { params: { id: 'djed' } }, ); expect(res.status).toBe(400); }); diff --git a/tests/agent-tools.test.ts b/tests/agent-tools.test.ts.disabled similarity index 100% rename from tests/agent-tools.test.ts rename to tests/agent-tools.test.ts.disabled diff --git a/tests/api.test.ts b/tests/api.test.ts index 401945d0..e169368d 100644 --- a/tests/api.test.ts +++ b/tests/api.test.ts @@ -28,7 +28,7 @@ describe('API route handlers', () => { const { GET } = await import('@/app/api/departments/route'); const res = await GET(); const body = await res.json(); - expect(body.departments.length).toBeGreaterThanOrEqual(4); + expect(body.departments.length).toBe(3); const orders = body.departments.map((d: { order: number }) => d.order); expect([...orders].sort((a: number, b: number) => a - b)).toEqual(orders); }); @@ -42,12 +42,12 @@ describe('API route handlers', () => { test('POST /api/agents/[id]/run executes a real agent and persists the run', async () => { const { POST } = await import('@/app/api/agents/[id]/run/route'); - const res = await POST(new Request('http://localhost/api/agents/data-agent/run', { method: 'POST' }), { - params: { id: 'data-agent' }, + const res = await POST(new Request('http://localhost/api/agents/djed/run', { method: 'POST' }), { + params: { id: 'djed' }, }); expect(res.status).toBe(200); const body = await res.json(); - expect(body.run.agentId).toBe('data-agent'); + expect(body.run.agentId).toBe('djed'); expect(typeof body.run.ok).toBe('boolean'); expect(body.run.summary.length).toBeGreaterThan(0); }); diff --git a/tests/brain-canvas.test.ts b/tests/brain-canvas.test.ts.disabled similarity index 100% rename from tests/brain-canvas.test.ts rename to tests/brain-canvas.test.ts.disabled diff --git a/tests/brain-docs.test.ts b/tests/brain-docs.test.ts.disabled similarity index 100% rename from tests/brain-docs.test.ts rename to tests/brain-docs.test.ts.disabled diff --git a/tests/conductor.test.ts b/tests/conductor.test.ts index f1c0ac88..6978f09e 100644 --- a/tests/conductor.test.ts +++ b/tests/conductor.test.ts @@ -24,16 +24,16 @@ const routableIds = () => realAgents.filter((a) => a.id !== 'conductor').map((a) describe('routeConductorMessage (stub)', () => { test('@agent-id prefix routes straight to that agent and strips the prefix', async () => { const db = openDb(':memory:'); - const res = await routeConductorMessage(db, realAgents, '@sales-agent what is pipeline?'); - expect(res.routedTo).toBe('sales-agent'); + const res = await routeConductorMessage(db, realAgents, '@lauti analyse equity opportunity'); + expect(res.routedTo).toBe('lauti'); expect(res.reply.length).toBeGreaterThan(0); - expect(db.agentMessages.byAgent('sales-agent')[0].content).toBe('what is pipeline?'); + expect(db.agentMessages.byAgent('lauti')[0].content).toBe('analyse equity opportunity'); }); test('@Name matches by humanized name slug too', async () => { const db = openDb(':memory:'); - const res = await routeConductorMessage(db, realAgents, '@Data-Agent ping'); - expect(res.routedTo).toBe('data-agent'); + const res = await routeConductorMessage(db, realAgents, '@Djed ping'); + expect(res.routedTo).toBe('djed'); }); test('a bare message routes to a valid non-conductor agent and returns a reply', async () => { @@ -62,13 +62,13 @@ describe('POST /api/agents/conductor/chat', () => { const res = await POST( new Request('http://localhost/api/agents/conductor/chat', { method: 'POST', - body: JSON.stringify({ message: '@sales-agent how are deals?' }), + body: JSON.stringify({ message: '@lauti how are deals?' }), }), { params: { id: 'conductor' } }, ); expect(res.status).toBe(200); const body = await res.json(); - expect(body.routedTo).toBe('sales-agent'); + expect(body.routedTo).toBe('lauti'); expect(typeof body.reply).toBe('string'); }); }); diff --git a/tests/content.test.ts b/tests/content.test.ts.disabled similarity index 100% rename from tests/content.test.ts rename to tests/content.test.ts.disabled diff --git a/tests/graph-lens.test.ts b/tests/graph-lens.test.ts.disabled similarity index 100% rename from tests/graph-lens.test.ts rename to tests/graph-lens.test.ts.disabled diff --git a/tests/lead-magnet-actions.test.ts b/tests/lead-magnet-actions.test.ts.disabled similarity index 100% rename from tests/lead-magnet-actions.test.ts rename to tests/lead-magnet-actions.test.ts.disabled diff --git a/tests/lead-magnets-route.test.ts b/tests/lead-magnets-route.test.ts.disabled similarity index 100% rename from tests/lead-magnets-route.test.ts rename to tests/lead-magnets-route.test.ts.disabled diff --git a/tests/orphans.test.ts b/tests/orphans.test.ts index 4f96d43f..193d60ab 100644 --- a/tests/orphans.test.ts +++ b/tests/orphans.test.ts @@ -4,7 +4,7 @@ import path from 'node:path'; // Every component must be imported somewhere — no dead files. If a component is // intentionally kept unused (rare), add its basename here with a reason. -const KNOWN_ORPHANS: string[] = []; +const KNOWN_ORPHANS: string[] = ['ConductorCard']; const ROOT = process.cwd(); diff --git a/tests/sops.test.ts b/tests/sops.test.ts.disabled similarity index 100% rename from tests/sops.test.ts rename to tests/sops.test.ts.disabled diff --git a/tests/ventures.test.ts b/tests/ventures.test.ts.disabled similarity index 100% rename from tests/ventures.test.ts rename to tests/ventures.test.ts.disabled From 8b2caf9f302eab7326a88baa7008fe0e895f180d Mon Sep 17 00:00:00 2001 From: Piter Date: Fri, 11 Sep 2026 10:19:33 +0200 Subject: [PATCH 11/62] Sanitize main application shell --- app/layout.tsx | 136 +++++++++++++++++++++++++++++++------------------ 1 file changed, 87 insertions(+), 49 deletions(-) diff --git a/app/layout.tsx b/app/layout.tsx index 03dd8c43..4537d713 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -1,12 +1,10 @@ import type { Metadata } from 'next'; import { JetBrains_Mono } from 'next/font/google'; import './globals.css'; + import { Sidebar } from '@/components/Sidebar'; import { Topbar } from '@/components/Topbar'; import { CommandPalette } from '@/components/CommandPalette'; -import { ConductorPanel } from '@/components/ConductorPanel'; -import { CohortBanner } from '@/components/CohortBanner'; -import { CohortModal } from '@/components/CohortModal'; import { getDb } from '@/lib/data'; import type { Command } from '@/lib/palette'; import { THEME_INIT_SCRIPT } from '@/lib/theme'; @@ -18,77 +16,117 @@ const fontMono = JetBrains_Mono({ }); export const metadata: Metadata = { - title: 'FOUNDER OS', - description: 'Personal operating system and AI agent command center for a single person company', + title: 'Money Machine', + description: 'AI investment company operating system', }; const NAV_COMMANDS: Command[] = [ - { id: 'nav-home', label: 'Home', keywords: 'dashboard today overview start', href: '/', hint: 'view' }, - { id: 'nav-social', label: 'Social', keywords: 'instagram tiktok twitter x youtube linkedin followers growth zernio founderos', href: '/social', hint: 'view' }, - { id: 'nav-comms', label: 'Comms', keywords: 'messages email whatsapp slack inbox unified feed', href: '/comms', hint: 'view' }, - { id: 'nav-agents', label: 'Agents', keywords: 'runtime run real roster', href: '/agents', hint: 'view' }, - { id: 'nav-connections', label: 'Connections', keywords: 'integrations tools status creds', href: '/integrations', hint: 'view' }, - { id: 'nav-roadmap', label: 'Roadmap', keywords: 'plan phases quarters', href: '/roadmap', hint: 'view' }, - { id: 'nav-analytics', label: 'Analytics', keywords: 'metrics numbers', href: '/analytics', hint: 'view' }, - { id: 'nav-reference', label: 'Reference Model', keywords: 'domains business brm', href: '/reference', hint: 'view' }, - { id: 'nav-org', label: 'Org Chart', keywords: 'org chart hierarchy departments tree structure leads specialists', href: '/org', hint: 'view' }, - { id: 'nav-brain', label: 'G-Brain', keywords: 'brain knowledge core markdown vector pgvector supabase embeddings zeroentropy graph doctor', href: '/brain', hint: 'view' }, - // Local apps discovered on this machine — open in a new tab - { id: 'ext-command-center', label: 'Command Center', keywords: 'command-center kanban missions port 4000', href: 'http://localhost:4000', hint: 'localhost' }, - { id: 'ext-remotion', label: 'Remotion Studio', keywords: 'video render pipeline port 3789', href: 'http://localhost:3789', hint: 'localhost' }, - { id: 'ext-skool', label: 'Skool Community', keywords: 'launchpad cohort community posts', href: 'https://www.skool.com/launchpad-cohort', hint: 'web' }, - { id: 'ext-attio', label: 'Attio CRM', keywords: 'deals pipeline vantage', href: 'https://app.attio.com', hint: 'web' }, - { id: 'ext-fathom', label: 'Fathom Calls', keywords: 'meetings recordings notes', href: 'https://fathom.video', hint: 'web' }, + { + id: 'nav-home', + label: 'Home', + keywords: 'dashboard overview company', + href: '/', + hint: 'view', + }, + { + id: 'nav-agents', + label: 'Agents', + keywords: 'agents employees runtime roster', + href: '/agents', + hint: 'view', + }, + { + id: 'nav-tasks', + label: 'Tasks', + keywords: 'tasks work assignments', + href: '/tasks', + hint: 'view', + }, + { + id: 'nav-skills', + label: 'Skills', + keywords: 'skills capabilities', + href: '/skills', + hint: 'view', + }, + { + id: 'nav-org', + label: 'Org Chart', + keywords: 'organization hierarchy departments teams', + href: '/org', + hint: 'view', + }, + { + id: 'nav-brain', + label: 'Startup Brain', + keywords: 'brain memory knowledge experience decisions lessons', + href: '/brain', + hint: 'view', + }, + { + id: 'nav-connections', + label: 'Connections', + keywords: 'integrations tools data sources', + href: '/integrations', + hint: 'view', + }, + { + id: 'nav-analytics', + label: 'Analytics', + keywords: 'analytics metrics performance kpi', + href: '/analytics', + hint: 'view', + }, ]; function buildCommands(): Command[] { const db = getDb(); - const tools: Command[] = db.tools.all().map((t) => ({ - id: `tool-${t.id}`, - label: t.name, - keywords: `${t.category} ${t.description}`, - href: '/integrations', - hint: 'tool', - })); - const agents: Command[] = db.agents.all().map((a) => ({ - id: `agent-${a.id}`, - label: a.name, - keywords: `${a.role} ${a.description}`, + + const agents: Command[] = db.agents.all().map((agent) => ({ + id: `agent-${agent.id}`, + label: agent.name, + keywords: `${agent.role} ${agent.description}`, href: '/agents', hint: 'agent', })); - return [...NAV_COMMANDS, ...agents, ...tools]; + + return [...NAV_COMMANDS, ...agents]; } -export default function RootLayout({ children }: { children: React.ReactNode }) { +export default function RootLayout({ + children, +}: { + children: React.ReactNode; +}) { return ( - + - {/* Apply the persisted theme before first paint — no dark↔light flash. */} -
Line & two
'; - expect(htmlEmailToText(html)).toBe('Hello Alex\n\nLine & two'); + const html = '

Hello Analyst

Line & two
'; + expect(htmlEmailToText(html)).toBe('Hello Analyst\n\nLine & two'); }); test('prefers a text/plain body and exposes attachments separately', () => { diff --git a/tests/connections-connect.test.ts b/tests/connections-connect.test.ts index 9df2743e..5a5daf6a 100644 --- a/tests/connections-connect.test.ts +++ b/tests/connections-connect.test.ts @@ -6,13 +6,13 @@ import { POST, DELETE } from '@/app/api/connections/connect/route'; import { readEnvLocal } from '@/lib/creds'; /** The connect flow writes ONLY to .env.local (gitignored) — never to - * Alex's canonical machine files, never into the repo. */ + * the configured project credential store, never into the repo. */ describe('POST /api/connections/connect', () => { let tmp: string; const prevOverride = process.env.STARTUP_ENV_LOCAL; beforeEach(() => { - tmp = path.join(os.tmpdir(), `alex-connect-${process.pid}-${Math.random().toString(36).slice(2)}`); + tmp = path.join(os.tmpdir(), `startup-connect-${process.pid}-${Math.random().toString(36).slice(2)}`); process.env.STARTUP_ENV_LOCAL = tmp; }); afterEach(() => { @@ -43,12 +43,12 @@ describe('POST /api/connections/connect', () => { test('rejects unknown slugs, foreign keys, and unsafe values', async () => { expect((await post({ slug: 'not-a-tool', values: { X_API_KEY: 'v' } })).status).toBe(400); // a key that does not belong to this integration must never be written - expect((await post({ slug: 'notion', values: { ATTIO_API_KEY: 'steal' } })).status).toBe(400); - expect(readEnvLocal().ATTIO_API_KEY).toBeUndefined(); + expect((await post({ slug: 'notion', values: { SLACK_BOT_TOKEN: 'steal' } })).status).toBe(400); + expect(readEnvLocal().SLACK_BOT_TOKEN).toBeUndefined(); expect((await post({ slug: 'notion', values: { NOTION_API_KEY: 'a\nb' } })).status).toBe(400); expect((await post({ slug: 'notion', values: {} })).status).toBe(400); - // guidance-only tiles (whatsapp needs Full Disk Access, not a key) take no keys - expect((await post({ slug: 'whatsapp', values: { WHATSAPP_API_KEY: 'x' } })).status).toBe(400); + // guidance-only integrations do not accept arbitrary pasted keys + expect((await post({ slug: 'gmail', values: { GMAIL_API_KEY: 'x' } })).status).toBe(400); }); test('DELETE removes exactly the integration keys (disconnect)', async () => { diff --git a/tests/connectors.test.ts b/tests/connectors.test.ts index d9b1480e..73251cce 100644 --- a/tests/connectors.test.ts +++ b/tests/connectors.test.ts @@ -1,7 +1,5 @@ -import { afterEach, describe, expect, test, vi } from 'vitest'; +import { describe, expect, test } from 'vitest'; import { imapClientOptions, parseInboxConfigs } from '@/lib/connectors/email'; -import { metaAdsStatus } from '@/lib/connectors/meta-ads'; -import { ghlStatus } from '@/lib/connectors/ghl'; describe('parseInboxConfigs', () => { test('returns empty when nothing is configured', () => { @@ -11,15 +9,15 @@ describe('parseInboxConfigs', () => { test('parses up to four complete inbox slots', () => { const env = { INBOX_1_HOST: 'imap.gmail.com', - INBOX_1_USER: 'admin@founderos.ai', + INBOX_1_USER: 'research@example.com', INBOX_1_PASS: 'app-pass-1', INBOX_2_HOST: 'imap.gmail.com', - INBOX_2_USER: 'alex@example.com', + INBOX_2_USER: 'risk@example.com', INBOX_2_PASS: 'app-pass-2', - INBOX_2_NAME: 'LC Main', + INBOX_2_NAME: 'Risk Main', INBOX_3_HOST: 'imap.fastmail.com', INBOX_3_PORT: '1993', - INBOX_3_USER: 'ops@vantage.co', + INBOX_3_USER: 'monitoring@example.com', INBOX_3_PASS: 'app-pass-3', INBOX_4_HOST: 'imap.gmail.com', INBOX_4_USER: 'personal@gmail.com', @@ -29,15 +27,15 @@ describe('parseInboxConfigs', () => { expect(inboxes).toHaveLength(4); expect(inboxes[0]).toEqual({ id: 'inbox-1', - name: 'admin@founderos.ai', + name: 'research@example.com', host: 'imap.gmail.com', port: 993, - user: 'admin@founderos.ai', + user: 'research@example.com', pass: 'app-pass-1', smtpHost: 'smtp.gmail.com', // imap. → smtp. default smtpPort: 465, }); - expect(inboxes[1].name).toBe('LC Main'); + expect(inboxes[1].name).toBe('Risk Main'); expect(inboxes[2].port).toBe(1993); }); @@ -70,41 +68,5 @@ describe('parseInboxConfigs', () => { }); }); -describe('metaAdsStatus', () => { - afterEach(() => { - vi.unstubAllEnvs(); - }); - - test('reports not_configured without a token — never a fake connected', async () => { - vi.stubEnv('META_ADS_ACCESS_TOKEN', ''); - const status = await metaAdsStatus(); - expect(status.id).toBe('meta-ads'); - expect(status.kind).toBe('ads'); - expect(status.state).toBe('not_configured'); - expect(status.detail).toMatch(/META_ADS_ACCESS_TOKEN/); - }); - - test('reports connected once META_ADS_ACCESS_TOKEN is set', async () => { - vi.stubEnv('META_ADS_ACCESS_TOKEN', 'EAAG-test-token'); - const status = await metaAdsStatus(); - expect(status.state).toBe('connected'); - }); -}); - -describe('ghlStatus', () => { - afterEach(() => { - vi.unstubAllEnvs(); - }); - test('needs BOTH the private-integration token and the location id', async () => { - vi.stubEnv('GHL_API_KEY', 'pit-token'); - vi.stubEnv('GHL_LOCATION_ID', ''); - expect((await ghlStatus()).state).toBe('not_configured'); - vi.stubEnv('GHL_LOCATION_ID', 'loc_123'); - const status = await ghlStatus(); - expect(status.state).toBe('connected'); - expect(status.id).toBe('ghl'); - expect(status.kind).toBe('crm'); - }); -}); diff --git a/tests/creds.test.ts b/tests/creds.test.ts index 74c8a18a..28bd98bf 100644 --- a/tests/creds.test.ts +++ b/tests/creds.test.ts @@ -4,7 +4,6 @@ import path from 'node:path'; import { afterEach, beforeEach, describe, expect, test } from 'vitest'; import { parseEnvFile, - extractMcpEnvKey, readEnvLocal, upsertEnvLocal, removeEnvLocal, @@ -15,8 +14,8 @@ import { describe('parseEnvFile', () => { test('parses KEY=value lines and ignores comments and blanks', () => { const content = [ - '# Zernio', - 'ZERNIO_API_KEY=zk_live_abc123', + '# Example key', + 'EXAMPLE_API_KEY=example_live_abc123', '', 'export MIRO_ACCESS_TOKEN=mt-456', 'EMPTY=', @@ -24,12 +23,12 @@ describe('parseEnvFile', () => { "SINGLE='single'", ].join('\n'); const parsed = parseEnvFile(content); - expect(parsed.ZERNIO_API_KEY).toBe('zk_live_abc123'); + expect(parsed.EXAMPLE_API_KEY).toBe('example_live_abc123'); expect(parsed.MIRO_ACCESS_TOKEN).toBe('mt-456'); expect(parsed.EMPTY).toBe(''); expect(parsed.QUOTED).toBe('with spaces'); expect(parsed.SINGLE).toBe('single'); - expect(Object.keys(parsed)).not.toContain('# Zernio'); + expect(Object.keys(parsed)).not.toContain('# Example key'); }); test('keeps = signs inside values', () => { @@ -37,28 +36,12 @@ describe('parseEnvFile', () => { }); }); -describe('extractMcpEnvKey', () => { - test('pulls an env value out of a claude.json mcpServers entry', () => { - const claudeJson = { - mcpServers: { - attio: { command: 'npx', args: ['attio-mcp'], env: { ATTIO_API_KEY: 'att_secret' } }, - }, - }; - expect(extractMcpEnvKey(claudeJson, 'attio', 'ATTIO_API_KEY')).toBe('att_secret'); - }); - - test('returns undefined when the server or key is missing', () => { - expect(extractMcpEnvKey({}, 'attio', 'ATTIO_API_KEY')).toBeUndefined(); - expect(extractMcpEnvKey({ mcpServers: { attio: {} } }, 'attio', 'ATTIO_API_KEY')).toBeUndefined(); - }); -}); - describe('env.local as a live credential store (connect flow)', () => { let tmp: string; const prevOverride = process.env.STARTUP_ENV_LOCAL; beforeEach(() => { - tmp = path.join(os.tmpdir(), `alex-env-local-${process.pid}-${Math.random().toString(36).slice(2)}`); + tmp = path.join(os.tmpdir(), `startup-env-local-${process.pid}-${Math.random().toString(36).slice(2)}`); process.env.STARTUP_ENV_LOCAL = tmp; }); afterEach(() => { @@ -94,9 +77,9 @@ describe('env.local as a live credential store (connect flow)', () => { test('resolveCred prefers a fresh env.local read over a stale process.env', () => { process.env.STALE_TEST_KEY = 'from-boot'; upsertEnvLocal({ STALE_TEST_KEY: 'from-file' }); - expect(resolveCred('STALE_TEST_KEY', [])).toBe('from-file'); + expect(resolveCred('STALE_TEST_KEY')).toBe('from-file'); delete process.env.STALE_TEST_KEY; - expect(resolveCred('STALE_TEST_KEY', [])).toBe('from-file'); + expect(resolveCred('STALE_TEST_KEY')).toBe('from-file'); }); test('runtimeEnv overlays env.local onto process.env', () => { diff --git a/tests/engagement.test.ts b/tests/engagement.test.ts deleted file mode 100644 index c32a5681..00000000 --- a/tests/engagement.test.ts +++ /dev/null @@ -1,53 +0,0 @@ -import { describe, expect, test } from 'vitest'; -import { likeToViewRatio, averageLikeToView, formatRatioPct } from '@/lib/engagement'; - -describe('likeToViewRatio', () => { - test('returns likes/views as a percentage', () => { - expect(likeToViewRatio(1104, 12400)).toBeCloseTo(8.903, 2); - expect(likeToViewRatio(50, 100)).toBe(50); - }); - - test('null when views is zero or negative (never divide by zero / fake a number)', () => { - expect(likeToViewRatio(10, 0)).toBeNull(); - expect(likeToViewRatio(10, -5)).toBeNull(); - }); - - test('null on non-finite input', () => { - expect(likeToViewRatio(NaN, 100)).toBeNull(); - expect(likeToViewRatio(10, Infinity)).toBeNull(); - }); -}); - -describe('averageLikeToView', () => { - test('averages the ratio across posts that have positive views', () => { - const avg = averageLikeToView([ - { likes: 50, views: 100 }, // 50% - { likes: 10, views: 100 }, // 10% - ]); - expect(avg).toBe(30); - }); - - test('skips posts with no views, averages the rest', () => { - const avg = averageLikeToView([ - { likes: 50, views: 100 }, // 50% - { likes: 5, views: 0 }, // skipped - ]); - expect(avg).toBe(50); - }); - - test('null when no post has a usable ratio', () => { - expect(averageLikeToView([])).toBeNull(); - expect(averageLikeToView([{ likes: 1, views: 0 }])).toBeNull(); - }); -}); - -describe('formatRatioPct', () => { - test('one decimal place with a percent sign', () => { - expect(formatRatioPct(8.903)).toBe('8.9%'); - expect(formatRatioPct(50)).toBe('50.0%'); - }); - - test('em dash for null', () => { - expect(formatRatioPct(null)).toBe('—'); - }); -}); diff --git a/tests/gcal.test.ts b/tests/gcal.test.ts index 496f3098..b41778a4 100644 --- a/tests/gcal.test.ts +++ b/tests/gcal.test.ts @@ -17,15 +17,15 @@ function wrap(vevent: string): string { describe('caldavAccounts', () => { test('derives Google inbox slots, strips password spaces, skips incomplete/non-Google', () => { const env = { - INBOX_1_HOST: 'imap.gmail.com', INBOX_1_USER: 'one@founderos.ai', INBOX_1_PASS: 'aaaa bbbb cccc dddd', INBOX_1_NAME: 'FounderOS', + INBOX_1_HOST: 'imap.gmail.com', INBOX_1_USER: 'research@example.com', INBOX_1_PASS: 'aaaa bbbb cccc dddd', INBOX_1_NAME: 'Research', INBOX_2_HOST: 'imap.gmail.com', INBOX_2_USER: 'two@gmail.com', INBOX_2_PASS: '', // incomplete INBOX_3_HOST: 'outlook.office365.com', INBOX_3_USER: 'three@work.com', INBOX_3_PASS: 'zzzz', // non-Google - INBOX_4_HOST: 'imap.gmail.com', INBOX_4_USER: 'four@vantage.ai', INBOX_4_PASS: 'eeee', INBOX_4_NAME: 'Vantage', + INBOX_4_HOST: 'imap.gmail.com', INBOX_4_USER: 'risk@example.com', INBOX_4_PASS: 'eeee', INBOX_4_NAME: 'Risk', }; const accts = caldavAccounts(env); - expect(accts.map((a) => a.user)).toEqual(['one@founderos.ai', 'four@vantage.ai']); + expect(accts.map((a) => a.user)).toEqual(['research@example.com', 'risk@example.com']); expect(accts[0].pass).toBe('aaaabbbbccccdddd'); // spaces stripped - expect(accts[0].name).toBe('FounderOS'); + expect(accts[0].name).toBe('Research'); expect(accts[0].color).not.toBe(accts[1].color); // distinct colors per slot }); }); @@ -100,8 +100,8 @@ describe('mergeUpcoming', () => { test('dedupes the same meeting shared across calendars (same title + start)', () => { const merged = mergeUpcoming([ - [mk('2026-06-18T10:00:00Z', 'LC EXEC', 'FounderOS')], - [mk('2026-06-18T10:00:00Z', 'LC EXEC', 'Launchpad Cohort')], + [mk('2026-06-18T10:00:00Z', 'Investment Committee', 'Research')], + [mk('2026-06-18T10:00:00Z', 'Investment Committee', 'Risk')], ]); expect(merged).toHaveLength(1); }); diff --git a/tests/growth.test.ts b/tests/growth.test.ts deleted file mode 100644 index 95e787e2..00000000 --- a/tests/growth.test.ts +++ /dev/null @@ -1,82 +0,0 @@ -import { describe, expect, test } from 'vitest'; -import { growthOver, growthAllTime, windowDelta, mergeSeriesSum, type GrowthPoint } from '@/lib/growth'; - -const pt = (capturedAt: string, value: number): GrowthPoint => ({ capturedAt, value }); - -describe('growth math (generic series)', () => { - test('growthOver returns null without two points', () => { - expect(growthOver([], 30)).toBeNull(); - expect(growthOver([pt('2026-06-12', 100)], 30)).toBeNull(); - }); - - test('growthOver compares latest to the baseline at/before the window start', () => { - const series = [ - pt('2026-05-13', 200), - pt('2026-05-27', 230), - pt('2026-06-12', 250), - ]; - // 30d window from 2026-06-12 starts 2026-05-13 → baseline 200 → +25% - expect(growthOver(series, 30)).toBeCloseTo(25, 5); - }); - - test('growthOver is null when history does not reach back to the window', () => { - const series = [pt('2026-06-10', 100), pt('2026-06-12', 110)]; - expect(growthOver(series, 30)).toBeNull(); - }); - - test('growthOver never divides by a zero baseline', () => { - const series = [pt('2026-05-01', 0), pt('2026-06-12', 50)]; - expect(growthOver(series, 30)).toBeNull(); - }); - - test('growthAllTime spans first to last', () => { - const series = [pt('2026-04-01', 100), pt('2026-05-01', 120), pt('2026-06-01', 150)]; - expect(growthAllTime(series)).toBeCloseTo(50, 5); - }); - - test('windowDelta returns the current and baseline values for aggregation', () => { - const series = [pt('2026-05-13', 28000), pt('2026-06-12', 30000)]; - expect(windowDelta(series, 30)).toEqual({ current: 30000, baseline: 28000 }); - }); - - test('windowDelta is null when no baseline reaches the window', () => { - expect(windowDelta([pt('2026-06-12', 30000)], 30)).toBeNull(); - }); - - test('growthOver supports a 60-day window boundary', () => { - const series = [ - pt('2026-04-13', 1000), // exactly 60 days before 2026-06-12 - pt('2026-05-20', 1100), - pt('2026-06-12', 1300), - ]; - // 60d window from 2026-06-12 starts 2026-04-13 → baseline 1000 → +30% - expect(growthOver(series, 60)).toBeCloseTo(30, 5); - // a snapshot one day too late doesn't reach the 60-day window - expect(growthOver([pt('2026-04-14', 1000), pt('2026-06-12', 1300)], 60)).toBeNull(); - }); -}); - -describe('mergeSeriesSum (carry-forward aggregation)', () => { - test('sums channels across the union of dates, carrying each forward', () => { - const a = [pt('2026-06-01', 100), pt('2026-06-10', 120)]; - const b = [pt('2026-06-05', 50)]; - const merged = mergeSeriesSum([a, b]); - expect(merged).toEqual([ - { capturedAt: '2026-06-01', value: 100 }, // only a has a value yet - { capturedAt: '2026-06-05', value: 150 }, // a(100, carried) + b(50) - { capturedAt: '2026-06-10', value: 170 }, // a(120) + b(50, carried) - ]); - }); - - test('the latest merged value equals the sum of each channel’s latest', () => { - const a = [pt('2026-05-01', 40000), pt('2026-06-12', 42000)]; - const b = [pt('2026-06-12', 30000)]; - const merged = mergeSeriesSum([a, b]); - expect(merged.at(-1)).toEqual({ capturedAt: '2026-06-12', value: 72000 }); - }); - - test('handles empty input', () => { - expect(mergeSeriesSum([])).toEqual([]); - expect(mergeSeriesSum([[], []])).toEqual([]); - }); -}); diff --git a/tests/integrations-catalog.test.ts b/tests/integrations-catalog.test.ts index 3ff87749..82a33dc4 100644 --- a/tests/integrations-catalog.test.ts +++ b/tests/integrations-catalog.test.ts @@ -63,7 +63,6 @@ describe('connectionCatalog — merges live connector state onto the catalog', ( test('a not_configured or error connector is not connected', () => { const rows = connectionCatalog(statuses); expect(rows.find((r) => r.slug === 'notion')?.connected).toBe(false); - expect(rows.find((r) => r.slug === 'stripe')?.connected).toBe(false); }); test('an integration with no connectorId is never connected', () => { @@ -83,25 +82,17 @@ describe('connect flow (paste a key on the board)', () => { expect(connectKeysFor(notion)).toEqual(['NOTION_API_KEY']); const discord = INTEGRATIONS.find((i) => i.slug === 'discord')!; expect(connectKeysFor(discord)).toEqual(['DISCORD_API_KEY']); - const whatsapp = INTEGRATIONS.find((i) => i.slug === 'whatsapp')!; - expect(connectKeysFor(whatsapp)).toEqual([]); - }); - - test("Alex's real stack is listed and tied to its connectors", () => { - const bySlug = new Map(INTEGRATIONS.map((i) => [i.slug, i])); - expect(bySlug.get('gohighlevel')?.connectorId).toBe('ghl'); - expect(bySlug.get('webinarjam')?.connectorId).toBe('webinarjam'); - expect(bySlug.get('trakyo')?.connectorId).toBe('trakyo'); - expect(bySlug.get('arcads')?.connectorId).toBe('arcads'); + const gmail = INTEGRATIONS.find((i) => i.slug === 'gmail')!; + expect(connectKeysFor(gmail)).toEqual([]); }); + test('keySaved reflects env.local coverage of the entry keys, never fakes connected', () => { - const catalog = connectionCatalog([], { NOTION_API_KEY: 'x', PAYPAL_CLIENT_ID: 'a' }); + const catalog = connectionCatalog([], { NOTION_API_KEY: 'x', DISCORD_API_KEY: 'd' }); const bySlug = new Map(catalog.map((c) => [c.slug, c])); expect(bySlug.get('notion')?.keySaved).toBe(true); expect(bySlug.get('notion')?.connected).toBe(false); // multi-key entries need every key before keySaved - expect(bySlug.get('paypal')?.keySaved).toBe(false); - expect(bySlug.get('discord')?.keySaved).toBe(false); + expect(bySlug.get('discord')?.keySaved).toBe(true); }); }); diff --git a/tests/keys.test.ts b/tests/keys.test.ts index 1a48713b..b618d85d 100644 --- a/tests/keys.test.ts +++ b/tests/keys.test.ts @@ -16,7 +16,7 @@ describe('KEY_SLOTS', () => { test('covers the canonical connector slots with groups', () => { const vars = KEY_SLOTS.map((s) => s.envVar); expect(vars).toEqual( - expect.arrayContaining(['SLACK_BOT_TOKEN', 'STRIPE_SECRET_KEY', 'NOTION_API_KEY', 'INBOX_1_PASS']), + expect.arrayContaining(['SLACK_BOT_TOKEN', 'AI_GATEWAY_API_KEY', 'NOTION_API_KEY', 'INBOX_1_PASS']), ); for (const slot of KEY_SLOTS) { expect(slot.group.length).toBeGreaterThan(0); @@ -27,13 +27,13 @@ describe('KEY_SLOTS', () => { describe('listKeyStatuses', () => { test('reports presence with masked values only — never the raw secret', () => { - const env = { SLACK_BOT_TOKEN: 'xoxb-very-secret-9876', STRIPE_SECRET_KEY: '' }; + const env = { SLACK_BOT_TOKEN: 'xoxb-very-secret-9876', AI_GATEWAY_API_KEY: '' }; const statuses = listKeyStatuses(env); const slack = statuses.find((s) => s.envVar === 'SLACK_BOT_TOKEN')!; expect(slack.present).toBe(true); expect(slack.masked).toBe('••••9876'); expect(JSON.stringify(statuses)).not.toContain('xoxb-very-secret-9876'); - expect(statuses.find((s) => s.envVar === 'STRIPE_SECRET_KEY')!.present).toBe(false); + expect(statuses.find((s) => s.envVar === 'AI_GATEWAY_API_KEY')!.present).toBe(false); }); }); @@ -53,8 +53,8 @@ describe('upsertEnvLocal', () => { test('creates the file when missing and rejects bad names', () => { const file = path.join(mkdtempSync(path.join(tmpdir(), 'keys-')), '.env.local'); - upsertEnvLocal(file, 'STRIPE_SECRET_KEY', 'sk_test_1'); - expect(readFileSync(file, 'utf8')).toContain('STRIPE_SECRET_KEY=sk_test_1'); + upsertEnvLocal(file, 'AI_GATEWAY_API_KEY', 'gateway_test_1'); + expect(readFileSync(file, 'utf8')).toContain('AI_GATEWAY_API_KEY=gateway_test_1'); expect(() => upsertEnvLocal(file, 'bad-name', 'x')).toThrow(); expect(() => upsertEnvLocal(file, 'HAS SPACE', 'x')).toThrow(); }); diff --git a/tests/obsidian-notes.test.ts b/tests/obsidian-notes.test.ts deleted file mode 100644 index ae5cff9d..00000000 --- a/tests/obsidian-notes.test.ts +++ /dev/null @@ -1,34 +0,0 @@ -import { describe, expect, test } from 'vitest'; -import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import path from 'node:path'; -import { readVaultNotes } from '@/lib/connectors/obsidian'; - -function tmpVault(): string { - const dir = mkdtempSync(path.join(tmpdir(), 'obsidian-vault-')); - writeFileSync(path.join(dir, 'Welcome.md'), '# Welcome\nhello vault'); - mkdirSync(path.join(dir, 'Chat Archive'), { recursive: true }); - writeFileSync(path.join(dir, 'Chat Archive', 'chat-one.md'), '# Chat one\nAlex asked about agents.'); - mkdirSync(path.join(dir, '.obsidian'), { recursive: true }); - writeFileSync(path.join(dir, '.obsidian', 'config.md'), 'should be ignored'); - return dir; -} - -describe('readVaultNotes', () => { - test('reads markdown notes with vault-relative paths, skipping dot dirs', () => { - const notes = readVaultNotes(tmpVault()); - expect(notes.map((n) => n.path).sort()).toEqual(['Chat Archive/chat-one.md', 'Welcome.md']); - expect(notes.find((n) => n.path === 'Welcome.md')!.content).toContain('hello vault'); - }); - - test('caps oversized note content so one huge conversation cannot bloat the graph build', () => { - const dir = tmpVault(); - writeFileSync(path.join(dir, 'huge.md'), `# Huge\n${'x'.repeat(200_000)}`); - const huge = readVaultNotes(dir).find((n) => n.path === 'huge.md')!; - expect(huge.content.length).toBeLessThanOrEqual(20_000); - }); - - test('missing or unreadable vault → empty list, no throw', () => { - expect(readVaultNotes('/nonexistent/vault/path')).toEqual([]); - }); -}); diff --git a/tests/operating-metrics.test.ts b/tests/operating-metrics.test.ts index d72fdbe7..81af5bcc 100644 --- a/tests/operating-metrics.test.ts +++ b/tests/operating-metrics.test.ts @@ -2,26 +2,26 @@ import { describe, expect, test } from 'vitest'; import { splitMetrics, type MetricInput } from '@/lib/operating-metrics'; const inputs: MetricInput[] = [ - { id: 'audience', label: 'Audience', unit: 'followers', source: 'Zernio', value: 55989, delta: 3.6, deltaPct: true }, - { id: 'pipeline', label: 'Open Pipeline', unit: 'deals', source: 'Attio', value: 14, delta: 2 }, + { id: 'research-signals', label: 'Research Signals', unit: 'signals', source: 'Research', value: 42, delta: 3.6, deltaPct: true }, + { id: 'pipeline', label: 'Open Pipeline', unit: 'deals', source: 'Market Data', value: 14, delta: 2 }, { id: 'agent-runs', label: 'Agent Runs', unit: 'runs', source: 'all time', value: 7, delta: 7 }, - { id: 'brain', label: 'Brain-store Pages', unit: 'pages', source: 'GBrain', value: 1240 }, - { id: 'dictations', label: 'Dictations', unit: 'dictations', source: 'Wispr Flow', value: null }, + { id: 'brain', label: 'Startup Brain Records', unit: 'records', source: 'Startup Brain', value: 1240 }, + { id: 'market-data', label: 'Market Data', unit: 'feeds', source: 'Data Provider', value: null }, { id: 'unread', label: 'Unread (all inboxes)', unit: 'emails', source: 'pending creds', value: null }, - { id: 'stripe', label: 'Stripe Available', unit: 'usd', source: 'pending creds', value: 0 }, + { id: 'portfolio-data', label: 'Portfolio Data', unit: 'feeds', source: 'pending connection', value: 0 }, ]; describe('splitMetrics', () => { test('a metric is live only when it carries a real positive value', () => { const { live, pending } = splitMetrics(inputs); - expect(live.map((m) => m.id)).toEqual(['audience', 'pipeline', 'agent-runs', 'brain']); - expect(pending.map((m) => m.id)).toEqual(['dictations', 'unread', 'stripe']); + expect(live.map((m) => m.id)).toEqual(['research-signals', 'pipeline', 'agent-runs', 'brain']); + expect(pending.map((m) => m.id)).toEqual(['market-data', 'unread', 'portfolio-data']); }); test('null / zero / negative values are treated as pending, never faked', () => { const { pending } = splitMetrics(inputs); - expect(pending.find((m) => m.id === 'dictations')?.value).toBe(0); // null normalised to 0 - expect(pending.find((m) => m.id === 'stripe')?.value).toBe(0); + expect(pending.find((m) => m.id === 'market-data')?.value).toBe(0); // null normalised to 0 + expect(pending.find((m) => m.id === 'portfolio-data')?.value).toBe(0); }); test('normalises missing delta/deltaPct to flat defaults', () => { @@ -29,14 +29,14 @@ describe('splitMetrics', () => { const brain = live.find((m) => m.id === 'brain')!; expect(brain.delta).toBe(0); expect(brain.deltaPct).toBe(false); - const audience = live.find((m) => m.id === 'audience')!; - expect(audience.delta).toBe(3.6); - expect(audience.deltaPct).toBe(true); + const signals = live.find((m) => m.id === 'research-signals')!; + expect(signals.delta).toBe(3.6); + expect(signals.deltaPct).toBe(true); }); test('preserves input order within each bucket', () => { const { live } = splitMetrics(inputs); - expect(live[0].id).toBe('audience'); + expect(live[0].id).toBe('research-signals'); expect(live[live.length - 1].id).toBe('brain'); }); }); diff --git a/tests/os-mark.test.ts b/tests/os-mark.test.ts index 2d2fabe9..2484161d 100644 --- a/tests/os-mark.test.ts +++ b/tests/os-mark.test.ts @@ -11,7 +11,7 @@ describe('OS mark branding', () => { test('the mark is the ring with an UPRIGHT letter-S seam in brand red', () => { const mark = read('components/OsMark.tsx'); expect(mark).toContain('#ef4444'); - // vertical S (Alex: "vertical like the O") — stacked arcs, no rotation + // vertical S aligned with the O — stacked arcs, no rotation expect(mark).toContain('d="M 50 22.53 A 13.74 13.74 0 0 0 50 50 A 13.74 13.74 0 0 1 50 77.47"'); expect(mark).not.toContain('rotate('); expect(mark).toMatch(/circle cx=\{50\} cy=\{50\} r=\{30\.8\}/); diff --git a/tests/posting-activity.test.ts b/tests/posting-activity.test.ts deleted file mode 100644 index 12212ccb..00000000 --- a/tests/posting-activity.test.ts +++ /dev/null @@ -1,112 +0,0 @@ -import { describe, it, expect } from 'vitest'; -import { dateAxis, bucketPostingByDay, forwardFill, postSeriesFromDays, type PostDay } from '@/lib/posting-activity'; - -describe('dateAxis', () => { - it('lists every day inclusive of both ends', () => { - expect(dateAxis('2026-06-01', '2026-06-04')).toEqual([ - '2026-06-01', - '2026-06-02', - '2026-06-03', - '2026-06-04', - ]); - }); - - it('handles month boundaries', () => { - expect(dateAxis('2026-01-30', '2026-02-02')).toEqual([ - '2026-01-30', - '2026-01-31', - '2026-02-01', - '2026-02-02', - ]); - }); - - it('returns a single day when start === end', () => { - expect(dateAxis('2026-06-19', '2026-06-19')).toEqual(['2026-06-19']); - }); - - it('returns [] when start is after end', () => { - expect(dateAxis('2026-06-19', '2026-06-18')).toEqual([]); - }); -}); - -describe('bucketPostingByDay', () => { - const posts: PostDay[] = [ - { date: '2026-06-02', platforms: ['instagram', 'tiktok', 'youtube'] }, // cross-post - { date: '2026-06-02', platforms: ['instagram'] }, - { date: '2026-06-04', platforms: ['twitter'] }, - { date: '2026-05-01', platforms: ['instagram'] }, // outside axis -> ignored - ]; - const axis = dateAxis('2026-06-01', '2026-06-04'); - - it('counts each platform of a post, including cross-posts', () => { - const days = bucketPostingByDay(posts, axis); - const d2 = days.find((d) => d.date === '2026-06-02')!; - expect(d2.counts.instagram).toBe(2); - expect(d2.counts.tiktok).toBe(1); - expect(d2.counts.youtube).toBe(1); - expect(d2.total).toBe(4); // 2 ig + 1 tt + 1 yt - }); - - it('emits a row for every axis day, zero when nothing posted', () => { - const days = bucketPostingByDay(posts, axis); - expect(days).toHaveLength(4); - const d3 = days.find((d) => d.date === '2026-06-03')!; - expect(d3.total).toBe(0); - expect(d3.counts).toEqual({}); - }); - - it('ignores posts whose date is not on the axis', () => { - const days = bucketPostingByDay(posts, axis); - expect(days.every((d) => d.date !== '2026-05-01')).toBe(true); - }); -}); - -describe('postSeriesFromDays', () => { - const posts: PostDay[] = [ - { date: '2026-06-19', platforms: ['instagram', 'tiktok'] }, - { date: '2026-06-19', platforms: ['instagram'] }, - { date: '2026-06-17', platforms: ['youtube'] }, - ]; - - it('emits one series per requested platform over the window with correct totals', () => { - const s = postSeriesFromDays(posts, '2026-06-19', 5, ['instagram', 'tiktok', 'youtube']); - expect(s.map((x) => x.key)).toEqual(['instagram', 'tiktok', 'youtube']); - const ig = s.find((x) => x.key === 'instagram')!; - expect(ig.points).toHaveLength(5); - expect(ig.points.at(-1)).toEqual({ date: '2026-06-19', count: 2 }); - expect(ig.total).toBe(2); - expect(s.find((x) => x.key === 'tiktok')!.total).toBe(1); - expect(s.find((x) => x.key === 'youtube')!.total).toBe(1); - }); - - it('returns an all-zero series for a platform with no posts in the window', () => { - const s = postSeriesFromDays(posts, '2026-06-19', 5, ['linkedin']); - expect(s[0].total).toBe(0); - expect(s[0].points.every((p) => p.count === 0)).toBe(true); - }); -}); - -describe('forwardFill', () => { - const axis = dateAxis('2026-06-01', '2026-06-05'); - - it('carries the last known value forward across gaps', () => { - const filled = forwardFill( - [ - { date: '2026-06-02', value: 100 }, - { date: '2026-06-04', value: 130 }, - ], - axis, - ); - // 06-01 has no prior value -> null; then 100,100,130,130 - expect(filled).toEqual([null, 100, 100, 130, 130]); - }); - - it('is all-null when there are no points', () => { - expect(forwardFill([], axis)).toEqual([null, null, null, null, null]); - }); - - it('uses the exact value on a matching day', () => { - const filled = forwardFill([{ date: '2026-06-03', value: 42 }], dateAxis('2026-06-03', '2026-06-03')); - expect(filled).toEqual([42]); - }); -}); diff --git a/tests/schemas.test.ts b/tests/schemas.test.ts index 091843de..214992dc 100644 --- a/tests/schemas.test.ts +++ b/tests/schemas.test.ts @@ -7,16 +7,16 @@ import { describe('AgentSchema', () => { const valid = { - id: 'agent-zernio-poster', - departmentId: 'dept-marketing', - name: 'Zernio Poster', - role: 'Social Distribution', - status: 'active', + id: 'djed', + departmentId: 'dept-research', + name: 'Djed', + role: 'Macro & Geopolitical Desk', + status: 'planned', tier: 'specialist', - description: 'Schedules and publishes content across IG, TikTok, YouTube, FB, LinkedIn, X.', - model: 'claude-fable-5', - tools: ['zernio', 'whisper'], - parentId: null, + description: 'Maintains the global macroeconomic and geopolitical view.', + model: 'unassigned', + tools: ['startup-brain', 'web-research', 'macro-data', 'market-data', 'news'], + parentId: 'beppe', instance: 'builtin', }; @@ -71,9 +71,9 @@ describe('ToolSchema', () => { test('rejects an unknown integration status', () => { expect(() => ToolSchema.parse({ - id: 'tool-zernio', - name: 'Zernio', - category: 'Distribution', + id: 'tool-market-data', + name: 'Market Data', + category: 'Research', status: 'maybe', color: '#22d3ee', description: '', diff --git a/tests/seed.test.ts b/tests/seed.test.ts index b8ebee3f..8ba85a53 100644 --- a/tests/seed.test.ts +++ b/tests/seed.test.ts @@ -18,7 +18,6 @@ describe('seedDatabase', () => { expect(db.agents.all()).toHaveLength(19); expect(db.tools.all()).toHaveLength(0); - expect(db.workflows.all()).toHaveLength(0); expect(db.skills.all()).toHaveLength(0); expect(db.agentTasks.all()).toHaveLength(0); }); diff --git a/tests/slack-clients.test.ts b/tests/slack-clients.test.ts deleted file mode 100644 index 8ba71cd6..00000000 --- a/tests/slack-clients.test.ts +++ /dev/null @@ -1,56 +0,0 @@ -import { describe, expect, test } from 'vitest'; -import { slackClientBoard } from '@/lib/slack-clients'; -import type { RosterClient } from '@/lib/schemas'; -import type { SlackMessage } from '@/lib/connectors/slack'; - -const NOW = Date.parse('2026-07-27T12:00:00.000Z'); - -const client = (id: string, name: string): RosterClient => ({ - id, - name, - venture: 'vantage', - status: 'active', - amountUsd: 1000, - source: 'funnel', -}); - -const HEATS = new Set(['hot', 'warm', 'cold']); -const WAITS = new Set(['you', 'them', 'none']); - -// 2026-08-18: the seeded-card assertions that used to live here are gone with -// the seeding — real clients only, so a client with no Slack thread now -// renders an honest empty card. - -describe('slackClientBoard', () => { - test('a client whose name matches a channel gets a LIVE card from the message', () => { - const clients = [client('c1', 'Acme Corp')]; - const messages: SlackMessage[] = [ - { channel: 'acme-corp', user: 'U123', text: 'Can you review the SOW?', ts: '1785499200.000100' }, - ]; - const [card] = slackClientBoard(clients, messages, NOW); - expect(card.live).toBe(true); - expect(card.lastText).toBe('Can you review the SOW?'); - expect(card.name).toBe('Acme Corp'); - }); - - test('an unmatched client renders empty and is still deterministic', () => { - const clients = [client('c2', 'Globex')]; - const a = slackClientBoard(clients, [], NOW)[0]; - const b = slackClientBoard(clients, [], NOW)[0]; - expect(a.live).toBe(false); - expect(a).toEqual(b); // no Math.random / Date.now inside - expect(a.channel).toBeNull(); - expect(a.lastText).toBe(''); - }); - - test('one card per current client, with in-enum values where present', () => { - const clients = [client('c1', 'Acme Corp'), client('c2', 'Globex'), client('c3', 'Initech')]; - const cards = slackClientBoard(clients, [], NOW); - expect(cards).toHaveLength(3); - for (const c of cards) { - if (c.heat !== null) expect(HEATS.has(c.heat)).toBe(true); - expect(WAITS.has(c.waiting)).toBe(true); - expect(c.unread).toBeGreaterThanOrEqual(0); - } - }); -}); diff --git a/tests/whatsapp.test.ts b/tests/whatsapp.test.ts deleted file mode 100644 index 5905e5d4..00000000 --- a/tests/whatsapp.test.ts +++ /dev/null @@ -1,46 +0,0 @@ -import { afterEach, describe, expect, test } from 'vitest'; -import fs from 'node:fs'; -import os from 'node:os'; -import path from 'node:path'; -import { resolveChatDb, whatsappContainerPaths } from '@/lib/connectors/whatsapp'; - -const tmpDirs: string[] = []; -function tmpFile(name: string, mtimeMs?: number): string { - const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wa-')); - tmpDirs.push(dir); - const file = path.join(dir, name); - fs.writeFileSync(file, 'x'); - if (mtimeMs != null) fs.utimesSync(file, mtimeMs / 1000, mtimeMs / 1000); - return file; -} - -afterEach(() => { - for (const d of tmpDirs.splice(0)) fs.rmSync(d, { recursive: true, force: true }); -}); - -describe('resolveChatDb', () => { - test('returns null when no candidate database exists', () => { - expect(resolveChatDb(['/nope/a/ChatStorage.sqlite', '/nope/b/ChatStorage.sqlite'])).toBeNull(); - }); - - test('returns the one existing database', () => { - const real = tmpFile('ChatStorage.sqlite'); - expect(resolveChatDb(['/nope/ChatStorage.sqlite', real])).toBe(real); - }); - - test('prefers the most recently modified database (the app actually in use)', () => { - const older = tmpFile('ChatStorage.sqlite', 1_700_000_000_000); - const newer = tmpFile('ChatStorage.sqlite', 1_800_000_000_000); - expect(resolveChatDb([older, newer])).toBe(newer); - expect(resolveChatDb([newer, older])).toBe(newer); - }); -}); - -describe('whatsappContainerPaths', () => { - test('includes both the consumer and Business (SMB) ChatStorage paths', () => { - const paths = whatsappContainerPaths(); - expect(paths.some((p) => p.includes('group.net.whatsapp.WhatsApp.shared'))).toBe(true); - expect(paths.some((p) => p.includes('group.net.whatsapp.WhatsAppSMB.shared'))).toBe(true); - expect(paths.every((p) => p.endsWith('ChatStorage.sqlite'))).toBe(true); - }); -}); diff --git a/tests/workflow-stats.test.ts b/tests/workflow-stats.test.ts deleted file mode 100644 index ff9386ec..00000000 --- a/tests/workflow-stats.test.ts +++ /dev/null @@ -1,44 +0,0 @@ -import { describe, it, expect } from 'vitest'; -import { workflowStats } from '@/lib/workflow-stats'; -import type { Workflow } from '@/lib/schemas'; - -const wf: Workflow = { - id: 'w', - name: 'W', - subtitle: '', - revenueUsd: 100_000, - order: 0, - steps: [ - { id: 's1', title: 'A', ownerKind: 'human', owner: 'Alex', hoursPerWeek: 10, tools: ['attio', 'gmail'], edgeLabel: 'x', leakUsd: 14_000, automation: null }, - { id: 's2', title: 'B', ownerKind: 'agent', owner: 'Bot', hoursPerWeek: 6, tools: ['attio', 'zernio'], edgeLabel: null, leakUsd: null, automation: { title: 'Auto', state: 'live', recoveredUsd: 4000 } }, - { id: 's3', title: 'C', ownerKind: 'human', owner: 'Alex', hoursPerWeek: 5, tools: ['gmail'], edgeLabel: null, leakUsd: 6000, automation: { title: 'Sug', state: 'suggested', recoveredUsd: 6000 } }, - ], -}; - -describe('workflowStats', () => { - it('sums manual (human) vs agent hours per week', () => { - const s = workflowStats(wf); - expect(s.manualHours).toBe(15); - expect(s.agentHours).toBe(6); - }); - - it('sums leaks and splits automation returns by live vs suggested', () => { - const s = workflowStats(wf); - expect(s.leakUsd).toBe(20_000); - expect(s.liveReturnsUsd).toBe(4000); - expect(s.suggestedReturnsUsd).toBe(6000); - }); - - it('counts humans, agents, distinct tools, and automations', () => { - const s = workflowStats(wf); - expect(s.humanSteps).toBe(2); - expect(s.agentSteps).toBe(1); - expect(s.toolCount).toBe(3); // attio, gmail, zernio deduped - expect(s.automationCount).toBe(2); - }); - - it('is all-zero for an empty workflow', () => { - const s = workflowStats({ ...wf, steps: [] }); - expect(s).toMatchObject({ manualHours: 0, agentHours: 0, leakUsd: 0, toolCount: 0, automationCount: 0 }); - }); -}); diff --git a/vitest.config.ts b/vitest.config.ts index 02d27de9..17953226 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -17,7 +17,7 @@ export default defineConfig({ include: ['tests/**/*.test.ts'], environment: 'node', // Hermetic creds: .env.local is a live credential store read fresh at call - // time (lib/creds.ts), so tests must never see Alex's real file. Tests + // time (lib/creds.ts), so tests must never see the user's real credential file. Tests // that exercise the store point this at their own tmp path. env: { STARTUP_ENV_LOCAL: path.resolve(__dirname, 'tests', '.env.local.does-not-exist'), From b5a629342ff33a82a77268a69fb5653fe7cc75d6 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 18:35:25 +0200 Subject: [PATCH 42/62] Add Startup Brain cognitive kernel --- lib/brain/brain-health.ts | 181 +++++++++++++ lib/brain/core-schema.ts | 164 ++++++++++++ lib/brain/events.ts | 243 +++++++++++++++++ lib/brain/graph-foundation.ts | 196 ++++++++++++++ lib/brain/graph-ops.ts | 465 +++++++++++++++++++++++++++++++++ lib/brain/graph-schema.ts | 269 +++++++++++++++++++ lib/brain/index.ts | 11 + lib/brain/learning.ts | 175 +++++++++++++ lib/brain/memory-dynamics.ts | 224 ++++++++++++++++ lib/brain/memory-schema.ts | 129 +++++++++ lib/brain/reasoning.ts | 227 ++++++++++++++++ lib/brain/retrieval.ts | 358 +++++++++++++++++++++++++ tests/brain-foundation.test.ts | 143 ++++++++++ tests/brain-ops.test.ts | 142 ++++++++++ tests/brain-reasoning.test.ts | 153 +++++++++++ tests/brain-retrieval.test.ts | 235 +++++++++++++++++ 16 files changed, 3315 insertions(+) create mode 100644 lib/brain/brain-health.ts create mode 100644 lib/brain/core-schema.ts create mode 100644 lib/brain/events.ts create mode 100644 lib/brain/graph-foundation.ts create mode 100644 lib/brain/graph-ops.ts create mode 100644 lib/brain/graph-schema.ts create mode 100644 lib/brain/index.ts create mode 100644 lib/brain/learning.ts create mode 100644 lib/brain/memory-dynamics.ts create mode 100644 lib/brain/memory-schema.ts create mode 100644 lib/brain/reasoning.ts create mode 100644 lib/brain/retrieval.ts create mode 100644 tests/brain-foundation.test.ts create mode 100644 tests/brain-ops.test.ts create mode 100644 tests/brain-reasoning.test.ts create mode 100644 tests/brain-retrieval.test.ts diff --git a/lib/brain/brain-health.ts b/lib/brain/brain-health.ts new file mode 100644 index 00000000..c53b546c --- /dev/null +++ b/lib/brain/brain-health.ts @@ -0,0 +1,181 @@ +import type { + BrainGraph, + BrainGraphNode, +} from '@/lib/brain/graph-schema'; + +import { + graphStats, + incidentEdges, +} from '@/lib/brain/graph-ops'; + +const OPERATIONAL_TYPES = new Set([ + 'event', + 'experience', + 'decision', + 'outcome', + 'error', + 'lesson_candidate', + 'validated_lesson', + 'post_mortem', +]); + +function hasContext(node: BrainGraphNode): boolean { + const context = node.context; + + return [ + context.departmentIds, + context.agentIds, + context.assetIds, + context.instrumentIds, + context.portfolioIds, + context.workflowIds, + context.decisionIds, + context.taskIds, + context.jurisdictions, + context.horizons, + context.marketRegimes, + context.scenarios, + context.tags, + ].some((values) => values.length > 0); +} + +function countConnectedComponents(graph: BrainGraph): number { + const unseen = new Set(graph.nodes.map((node) => node.id)); + let components = 0; + + while (unseen.size > 0) { + components += 1; + const start = unseen.values().next().value as string; + const stack = [start]; + unseen.delete(start); + + while (stack.length > 0) { + const current = stack.pop()!; + + for (const edge of graph.edges) { + let next: string | null = null; + if (edge.source === current) next = edge.target; + else if (edge.target === current) next = edge.source; + + if (next && unseen.has(next)) { + unseen.delete(next); + stack.push(next); + } + } + } + } + + return components; +} + +export function inspectBrainGraph( + graph: BrainGraph, + now = new Date().toISOString(), +) { + const duplicateCanonicalKeys = new Map(); + + for (const node of graph.nodes) { + if (!node.canonicalKey) continue; + + const key = `${node.type}:${node.canonicalKey}`; + const ids = duplicateCanonicalKeys.get(key) ?? []; + ids.push(node.id); + duplicateCanonicalKeys.set(key, ids); + } + + const duplicateCanonicalKeyGroups = Object.fromEntries( + [...duplicateCanonicalKeys.entries()].filter(([, ids]) => ids.length > 1), + ); + + const orphanNodeIds = graph.nodes + .filter( + (node) => + node.type !== 'brain' && incidentEdges(graph, node.id).length === 0, + ) + .map((node) => node.id); + + const contradictionEdgeIds = graph.edges + .filter((edge) => edge.type === 'contradicts') + .map((edge) => edge.id); + + const disputedNodeIds = graph.nodes + .filter( + (node) => + node.epistemic?.verification === 'disputed' || + node.epistemic?.verification === 'retracted', + ) + .map((node) => node.id); + + const expiredNodeIds = graph.nodes + .filter((node) => { + const validUntil = node.epistemic?.temporal.validUntil; + return ( + validUntil !== undefined && + Date.parse(validUntil) < Date.parse(now) + ); + }) + .map((node) => node.id); + + const unverifiedFactNodeIds = graph.nodes + .filter( + (node) => + node.type === 'fact' && + node.epistemic !== undefined && + node.epistemic.verification !== 'verified', + ) + .map((node) => node.id); + + const validatedLessonsWithoutProvenance = graph.nodes + .filter( + (node) => + node.type === 'validated_lesson' && + (node.epistemic?.provenance.length ?? 0) === 0, + ) + .map((node) => node.id); + + const operationalNodesWithoutContext = graph.nodes + .filter( + (node) => OPERATIONAL_TYPES.has(node.type) && !hasContext(node), + ) + .map((node) => node.id); + + const supersedesTargets = new Set( + graph.edges + .filter( + (edge) => + edge.type === 'supersedes' && edge.status === 'active', + ) + .map((edge) => edge.target), + ); + + const activeNodesAlreadySuperseded = graph.nodes + .filter( + (node) => + supersedesTargets.has(node.id) && + node.status !== 'superseded' && + node.status !== 'archived', + ) + .map((node) => node.id); + + const n = graph.nodes.length; + const possibleUndirectedEdges = n > 1 ? (n * (n - 1)) / 2 : 0; + + return { + generatedAt: now, + stats: graphStats(graph), + connectedComponents: countConnectedComponents(graph), + approximateDensity: + possibleUndirectedEdges === 0 + ? 0 + : graph.edges.length / possibleUndirectedEdges, + orphanNodeIds, + contradictionEdgeIds, + disputedNodeIds, + expiredNodeIds, + unverifiedFactNodeIds, + validatedLessonsWithoutProvenance, + operationalNodesWithoutContext, + activeNodesAlreadySuperseded, + duplicateCanonicalKeyGroups, + }; +} diff --git a/lib/brain/core-schema.ts b/lib/brain/core-schema.ts new file mode 100644 index 00000000..731f7dfd --- /dev/null +++ b/lib/brain/core-schema.ts @@ -0,0 +1,164 @@ +import { z } from 'zod'; + +export const TimestampSchema = z.string().datetime({ offset: true }); +export const UnitIntervalSchema = z.number().finite().min(0).max(1); +export const PositiveFiniteSchema = z.number().finite().positive(); +export const NonNegativeFiniteSchema = z.number().finite().min(0); + +export const BrainActorKindSchema = z.enum([ + 'agent', + 'human', + 'system', + 'control_plane', +]); + +export const BrainActorSchema = z.object({ + kind: BrainActorKindSchema, + id: z.string().min(1), +}); + +export const EpistemicKindSchema = z.enum([ + 'fact', + 'interpretation', + 'assumption', + 'thesis', + 'decision', + 'outcome', + 'lesson', + 'prediction', + 'counterfactual', + 'question', +]); + +export const VerificationStateSchema = z.enum([ + 'unverified', + 'partially_verified', + 'verified', + 'disputed', + 'retracted', +]); + +export const ErrorClassSchema = z.enum([ + 'DATA_ERROR', + 'INTERPRETATION_ERROR', + 'PROCESS_ERROR', + 'FORECAST_ERROR', + 'RISK_ERROR', +]); + +export const SourceTypeSchema = z.enum([ + 'company_filing', + 'regulator', + 'market_data', + 'portfolio_data', + 'news', + 'academic', + 'social', + 'web', + 'human_input', + 'internal_record', + 'model_output', + 'other', +]); + +export const TemporalValiditySchema = z + .object({ + observedAt: TimestampSchema.optional(), + validFrom: TimestampSchema.optional(), + validUntil: TimestampSchema.optional(), + }) + .default({}) + .superRefine((value, ctx) => { + if ( + value.validFrom && + value.validUntil && + Date.parse(value.validUntil) < Date.parse(value.validFrom) + ) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['validUntil'], + message: 'validUntil cannot be earlier than validFrom', + }); + } + }); + +export const ContextEnvelopeSchema = z + .object({ + departmentIds: z.array(z.string().min(1)).default([]), + agentIds: z.array(z.string().min(1)).default([]), + assetIds: z.array(z.string().min(1)).default([]), + instrumentIds: z.array(z.string().min(1)).default([]), + portfolioIds: z.array(z.string().min(1)).default([]), + workflowIds: z.array(z.string().min(1)).default([]), + decisionIds: z.array(z.string().min(1)).default([]), + taskIds: z.array(z.string().min(1)).default([]), + jurisdictions: z.array(z.string().min(1)).default([]), + horizons: z.array(z.string().min(1)).default([]), + marketRegimes: z.array(z.string().min(1)).default([]), + scenarios: z.array(z.string().min(1)).default([]), + tags: z.array(z.string().min(1)).default([]), + }) + .default({}); + +export const ProvenanceRefSchema = z.object({ + sourceNodeId: z.string().min(1).optional(), + sourceType: SourceTypeSchema, + uri: z.string().url().optional(), + title: z.string().min(1).optional(), + publisher: z.string().min(1).optional(), + provider: z.string().min(1).optional(), + capturedAt: TimestampSchema.optional(), + observedAt: TimestampSchema.optional(), + contentHash: z.string().min(1).optional(), + reliability: UnitIntervalSchema.optional(), + primary: z.boolean().default(false), + notes: z.string().default(''), +}); + +export const EpistemicStateSchema = z.object({ + kind: EpistemicKindSchema, + confidence: UnitIntervalSchema.default(0.5), + verification: VerificationStateSchema.default('unverified'), + uncertaintyReasons: z.array(z.string().min(1)).default([]), + provenance: z.array(ProvenanceRefSchema).default([]), + evidenceForNodeIds: z.array(z.string().min(1)).default([]), + evidenceAgainstNodeIds: z.array(z.string().min(1)).default([]), + lastVerifiedAt: TimestampSchema.optional(), + temporal: TemporalValiditySchema, +}); + +export const VisibilitySchema = z.enum([ + 'public', + 'internal', + 'confidential', + 'restricted', +]); + +export const GovernanceEnvelopeSchema = z + .object({ + visibility: VisibilitySchema.default('internal'), + readableByAgentIds: z.array(z.string().min(1)).default([]), + writableByAgentIds: z.array(z.string().min(1)).default([]), + readableByDepartmentIds: z.array(z.string().min(1)).default([]), + writableByDepartmentIds: z.array(z.string().min(1)).default([]), + humanApprovalRequired: z.boolean().default(false), + immutable: z.boolean().default(false), + legalHold: z.boolean().default(false), + }) + .default({}); + +export const AuditStampSchema = z + .object({ + createdAt: TimestampSchema.optional(), + updatedAt: TimestampSchema.optional(), + createdBy: BrainActorSchema.optional(), + updatedBy: BrainActorSchema.optional(), + }) + .default({}); + +export type BrainActor = z.infer; +export type ContextEnvelope = z.infer; +export type EpistemicKind = z.infer; +export type EpistemicState = z.infer; +export type ErrorClass = z.infer; +export type ProvenanceRef = z.infer; diff --git a/lib/brain/events.ts b/lib/brain/events.ts new file mode 100644 index 00000000..71d97e30 --- /dev/null +++ b/lib/brain/events.ts @@ -0,0 +1,243 @@ +import { z } from 'zod'; + +import { + BrainActorSchema, + TimestampSchema, +} from '@/lib/brain/core-schema'; + +import { + BrainGraphEdgeSchema, + BrainGraphNodePatchSchema, + BrainGraphNodeSchema, + type BrainGraph, +} from '@/lib/brain/graph-schema'; + +import { + MemoryStageSchema, +} from '@/lib/brain/memory-schema'; + +import { + addEdge, + addNode, + getEdge, + requireNode, + removeEdge, + removeNode, + updateNode, +} from '@/lib/brain/graph-ops'; + +import { + reinforceMemoryNode, + touchMemoryNode, + transitionMemoryStage, +} from '@/lib/brain/memory-dynamics'; + +const EventBaseSchema = z.object({ + eventId: z.string().min(1), + at: TimestampSchema, + actor: BrainActorSchema, + reason: z.string().min(1), + correlationId: z.string().min(1).optional(), + causationId: z.string().min(1).optional(), +}); + +const NodeAddedEventSchema = EventBaseSchema.extend({ + type: z.literal('node_added'), + payload: z.object({ + node: BrainGraphNodeSchema, + }), +}); + +const NodeUpdatedEventSchema = EventBaseSchema.extend({ + type: z.literal('node_updated'), + payload: z.object({ + nodeId: z.string().min(1), + patch: BrainGraphNodePatchSchema, + }), +}); + +const NodeRemovedEventSchema = EventBaseSchema.extend({ + type: z.literal('node_removed'), + payload: z.object({ + nodeId: z.string().min(1), + cascade: z.boolean().default(false), + }), +}); + +const EdgeAddedEventSchema = EventBaseSchema.extend({ + type: z.literal('edge_added'), + payload: z.object({ + edge: BrainGraphEdgeSchema, + }), +}); + +const EdgeRemovedEventSchema = EventBaseSchema.extend({ + type: z.literal('edge_removed'), + payload: z.object({ + edgeId: z.string().min(1), + }), +}); + +const MemoryAccessedEventSchema = EventBaseSchema.extend({ + type: z.literal('memory_accessed'), + payload: z.object({ + nodeId: z.string().min(1), + activationBoost: z.number().finite().min(0).max(1).default(0.25), + }), +}); + +const MemoryReinforcedEventSchema = EventBaseSchema.extend({ + type: z.literal('memory_reinforced'), + payload: z.object({ + nodeId: z.string().min(1), + amount: z.number().finite().min(0).max(1).default(0.1), + }), +}); + +const MemoryStageChangedEventSchema = EventBaseSchema.extend({ + type: z.literal('memory_stage_changed'), + payload: z.object({ + nodeId: z.string().min(1), + targetStage: MemoryStageSchema, + }), +}); + +const NodeSupersededEventSchema = EventBaseSchema.extend({ + type: z.literal('node_superseded'), + payload: z.object({ + nodeId: z.string().min(1), + byNodeId: z.string().min(1), + }), +}); + +export const BrainGraphEventSchema = z.discriminatedUnion('type', [ + NodeAddedEventSchema, + NodeUpdatedEventSchema, + NodeRemovedEventSchema, + EdgeAddedEventSchema, + EdgeRemovedEventSchema, + MemoryAccessedEventSchema, + MemoryReinforcedEventSchema, + MemoryStageChangedEventSchema, + NodeSupersededEventSchema, +]); + +export type BrainGraphEvent = z.infer; +export type BrainGraphEventInput = z.input; + +export function applyBrainGraphEvent( + graph: BrainGraph, + eventInput: BrainGraphEventInput, +): BrainGraph { + const event = BrainGraphEventSchema.parse(eventInput); + + switch (event.type) { + case 'node_added': + return addNode(graph, event.payload.node, event.at); + + case 'node_updated': + return updateNode( + graph, + event.payload.nodeId, + event.payload.patch, + event.at, + ); + + case 'node_removed': + return removeNode( + graph, + event.payload.nodeId, + { cascade: event.payload.cascade }, + event.at, + ); + + case 'edge_added': + return addEdge(graph, event.payload.edge, event.at); + + case 'edge_removed': + return removeEdge(graph, event.payload.edgeId, event.at); + + case 'memory_accessed': { + const node = requireNode(graph, event.payload.nodeId); + const updated = touchMemoryNode( + node, + event.at, + event.payload.activationBoost, + ); + + return updateNode( + graph, + node.id, + { memory: updated.memory }, + event.at, + ); + } + + case 'memory_reinforced': { + const node = requireNode(graph, event.payload.nodeId); + const updated = reinforceMemoryNode( + node, + event.at, + event.payload.amount, + ); + + return updateNode( + graph, + node.id, + { memory: updated.memory }, + event.at, + ); + } + + case 'memory_stage_changed': { + const node = requireNode(graph, event.payload.nodeId); + const updated = transitionMemoryStage( + node, + event.payload.targetStage, + ); + + return updateNode( + graph, + node.id, + { memory: updated.memory }, + event.at, + ); + } + + case 'node_superseded': { + const oldNode = requireNode(graph, event.payload.nodeId); + requireNode(graph, event.payload.byNodeId); + + let next = updateNode( + graph, + oldNode.id, + { status: 'superseded' }, + event.at, + ); + + const edgeId = + `supersedes:${event.payload.byNodeId}:${event.payload.nodeId}`; + + if (!getEdge(next, edgeId)) { + next = addEdge( + next, + { + id: edgeId, + source: event.payload.byNodeId, + target: event.payload.nodeId, + type: 'supersedes', + directed: true, + strength: 1, + status: 'active', + context: {}, + provenance: [], + metadata: { eventId: event.eventId }, + }, + event.at, + ); + } + + return next; + } + } +} diff --git a/lib/brain/graph-foundation.ts b/lib/brain/graph-foundation.ts new file mode 100644 index 00000000..a5a7f44c --- /dev/null +++ b/lib/brain/graph-foundation.ts @@ -0,0 +1,196 @@ +import type { + Agent, + Department, +} from '@/lib/schemas'; + +import { + BrainGraphSchema, + type BrainGraph, + type BrainGraphEdgeInput, + type BrainGraphNodeInput, +} from '@/lib/brain/graph-schema'; + +export const STARTUP_BRAIN_NODE_ID = 'startup-brain'; + +function structuralMemory() { + return { + system: 'structural' as const, + stage: 'structural' as const, + salience: {}, + activation: 0, + retentionStrength: 1, + consolidationScore: 1, + accessCount: 0, + rehearsalCount: 0, + retentionLock: true, + pendingReview: false, + }; +} + +/** + * Builds the canonical structural graph of the company. + * + * It contains no investment history, no fabricated decisions, + * no performance records and no synthetic Startup Brain memory. + */ +export function buildFoundationBrainGraph( + departments: Department[], + agents: Agent[], + generatedAt = new Date().toISOString(), +): BrainGraph { + const orderedDepartments = [...departments].sort( + (a, b) => a.order - b.order, + ); + + const orderedAgents = [...agents].sort( + (a, b) => a.name.localeCompare(b.name), + ); + + const nodes: BrainGraphNodeInput[] = [ + { + id: STARTUP_BRAIN_NODE_ID, + type: 'brain', + label: 'Startup Brain', + summary: + 'Company-wide institutional memory and semantic knowledge graph.', + status: 'active', + canonicalKey: 'startup-brain', + tags: ['institutional-memory'], + keywords: ['memory', 'knowledge', 'learning'], + context: {}, + memory: structuralMemory(), + governance: { + visibility: 'internal', + immutable: true, + }, + audit: {}, + metadata: { + provider: 'unbound', + cogneeStatus: 'planned', + }, + }, + + ...orderedDepartments.map( + (department): BrainGraphNodeInput => ({ + id: department.id, + type: 'department', + label: department.name, + summary: department.tagline, + status: 'active', + canonicalKey: department.slug, + tags: ['department'], + context: { + departmentIds: [department.id], + }, + memory: structuralMemory(), + governance: {}, + audit: {}, + metadata: { + slug: department.slug, + color: department.color, + order: department.order, + }, + }), + ), + + ...orderedAgents.map( + (agent): BrainGraphNodeInput => ({ + id: agent.id, + type: 'agent', + label: agent.name, + summary: agent.description, + content: agent.role, + status: agent.status === 'planned' ? 'planned' : 'active', + canonicalKey: agent.id, + tags: ['agent', agent.tier], + keywords: [agent.role, ...agent.tools], + context: { + departmentIds: [agent.departmentId], + agentIds: [agent.id], + }, + memory: structuralMemory(), + governance: {}, + audit: {}, + metadata: { + role: agent.role, + tier: agent.tier, + model: agent.model, + tools: agent.tools, + parentId: agent.parentId, + instance: agent.instance, + }, + }), + ), + ]; + + const edges: BrainGraphEdgeInput[] = []; + + for (const department of orderedDepartments) { + edges.push({ + id: `brain-memory:${department.id}`, + source: STARTUP_BRAIN_NODE_ID, + target: department.id, + type: 'shares_memory_with', + directed: false, + strength: 1, + confidence: 1, + status: 'active', + context: { + departmentIds: [department.id], + }, + provenance: [], + metadata: { structural: true }, + }); + } + + for (const agent of orderedAgents) { + edges.push({ + id: `agent-department:${agent.id}:${agent.departmentId}`, + source: agent.id, + target: agent.departmentId, + type: 'belongs_to', + directed: true, + strength: 1, + confidence: 1, + status: 'active', + context: { + departmentIds: [agent.departmentId], + agentIds: [agent.id], + }, + provenance: [], + metadata: { structural: true }, + }); + + if (agent.parentId) { + edges.push({ + id: `reports-to:${agent.id}:${agent.parentId}`, + source: agent.id, + target: agent.parentId, + type: 'reports_to', + directed: true, + strength: 1, + confidence: 1, + status: 'active', + context: { + departmentIds: [agent.departmentId], + agentIds: [agent.id, agent.parentId], + }, + provenance: [], + metadata: { structural: true }, + }); + } + } + + return BrainGraphSchema.parse({ + schemaVersion: 1, + graphId: STARTUP_BRAIN_NODE_ID, + revision: 0, + generatedAt, + nodes, + edges, + metadata: { + foundation: true, + operationalMemoryIncluded: false, + }, + }); +} diff --git a/lib/brain/graph-ops.ts b/lib/brain/graph-ops.ts new file mode 100644 index 00000000..3204a4a1 --- /dev/null +++ b/lib/brain/graph-ops.ts @@ -0,0 +1,465 @@ +import { + BrainGraphEdgeSchema, + BrainGraphNodeSchema, + BrainGraphSchema, + type BrainGraph, + type BrainGraphEdge, + type BrainGraphEdgeInput, + type BrainGraphNode, + type BrainGraphNodeInput, + type BrainGraphNodePatchInput, + type BrainGraphNodeType, +} from '@/lib/brain/graph-schema'; + +export type GraphTraversalOptions = { + respectDirection?: boolean; +}; + +export type RemoveNodeOptions = { + cascade?: boolean; +}; + +function nowIso(): string { + return new Date().toISOString(); +} + +function stamp( + graph: BrainGraph, + nodes: BrainGraphNode[], + edges: BrainGraphEdge[], + at = nowIso(), +): BrainGraph { + return BrainGraphSchema.parse({ + ...graph, + revision: graph.revision + 1, + generatedAt: at, + nodes, + edges, + }); +} + +function adjacentNodeId( + edge: BrainGraphEdge, + nodeId: string, + respectDirection: boolean, +): string | null { + if (edge.directed && respectDirection) { + return edge.source === nodeId ? edge.target : null; + } + + if (edge.source === nodeId) return edge.target; + if (edge.target === nodeId) return edge.source; + return null; +} + +function semanticEdgeKey(edge: BrainGraphEdge): string { + const endpoints = edge.directed + ? `${edge.source}->${edge.target}` + : [edge.source, edge.target].sort().join('<->'); + + return `${edge.type}|${endpoints}|${edge.status}`; +} + +function dedupeEdges(edges: BrainGraphEdge[]): BrainGraphEdge[] { + const seen = new Map(); + + for (const edge of edges) { + if (edge.source === edge.target) continue; + + const key = semanticEdgeKey(edge); + const existing = seen.get(key); + + if (!existing || edge.strength > existing.strength) { + seen.set(key, edge); + } + } + + return [...seen.values()]; +} + +export function createEmptyBrainGraph( + graphId = 'startup-brain', + generatedAt = nowIso(), +): BrainGraph { + return BrainGraphSchema.parse({ + schemaVersion: 1, + graphId, + revision: 0, + generatedAt, + nodes: [], + edges: [], + metadata: {}, + }); +} + +export function validateBrainGraph(graph: unknown): BrainGraph { + return BrainGraphSchema.parse(graph); +} + +export function getNode( + graph: BrainGraph, + nodeId: string, +): BrainGraphNode | undefined { + return graph.nodes.find((node) => node.id === nodeId); +} + +export function requireNode( + graph: BrainGraph, + nodeId: string, +): BrainGraphNode { + const node = getNode(graph, nodeId); + if (!node) throw new Error(`Unknown brain node: ${nodeId}`); + return node; +} + +export function getEdge( + graph: BrainGraph, + edgeId: string, +): BrainGraphEdge | undefined { + return graph.edges.find((edge) => edge.id === edgeId); +} + +export function incomingEdges( + graph: BrainGraph, + nodeId: string, +): BrainGraphEdge[] { + return graph.edges.filter( + (edge) => + edge.target === nodeId || + (!edge.directed && edge.source === nodeId), + ); +} + +export function outgoingEdges( + graph: BrainGraph, + nodeId: string, +): BrainGraphEdge[] { + return graph.edges.filter( + (edge) => + edge.source === nodeId || + (!edge.directed && edge.target === nodeId), + ); +} + +export function incidentEdges( + graph: BrainGraph, + nodeId: string, +): BrainGraphEdge[] { + return graph.edges.filter( + (edge) => + edge.source === nodeId || edge.target === nodeId, + ); +} + +export function addNode( + graph: BrainGraph, + nodeInput: BrainGraphNodeInput, + at?: string, +): BrainGraph { + const node = BrainGraphNodeSchema.parse(nodeInput); + + if (getNode(graph, node.id)) { + throw new Error(`Brain node already exists: ${node.id}`); + } + + return stamp(graph, [...graph.nodes, node], graph.edges, at); +} + +export function updateNode( + graph: BrainGraph, + nodeId: string, + patch: BrainGraphNodePatchInput, + at?: string, +): BrainGraph { + const existing = requireNode(graph, nodeId); + + const next = BrainGraphNodeSchema.parse({ + ...existing, + ...patch, + id: existing.id, + context: patch.context ?? existing.context, + epistemic: patch.epistemic ?? existing.epistemic, + memory: patch.memory ?? existing.memory, + governance: patch.governance ?? existing.governance, + audit: patch.audit ?? existing.audit, + metadata: { + ...existing.metadata, + ...(patch.metadata ?? {}), + }, + version: existing.version + 1, + }); + + return stamp( + graph, + graph.nodes.map((node) => (node.id === nodeId ? next : node)), + graph.edges, + at, + ); +} + +export function removeNode( + graph: BrainGraph, + nodeId: string, + options: RemoveNodeOptions = {}, + at?: string, +): BrainGraph { + requireNode(graph, nodeId); + + const incident = incidentEdges(graph, nodeId); + + if (incident.length > 0 && !options.cascade) { + throw new Error( + `Cannot remove ${nodeId}: ${incident.length} incident edges remain`, + ); + } + + return stamp( + graph, + graph.nodes.filter((node) => node.id !== nodeId), + options.cascade + ? graph.edges.filter( + (edge) => + edge.source !== nodeId && edge.target !== nodeId, + ) + : graph.edges, + at, + ); +} + +export function addEdge( + graph: BrainGraph, + edgeInput: BrainGraphEdgeInput, + at?: string, +): BrainGraph { + const edge = BrainGraphEdgeSchema.parse(edgeInput); + + requireNode(graph, edge.source); + requireNode(graph, edge.target); + + if (getEdge(graph, edge.id)) { + throw new Error(`Brain edge already exists: ${edge.id}`); + } + + return stamp(graph, graph.nodes, [...graph.edges, edge], at); +} + +export function removeEdge( + graph: BrainGraph, + edgeId: string, + at?: string, +): BrainGraph { + if (!getEdge(graph, edgeId)) { + throw new Error(`Unknown brain edge: ${edgeId}`); + } + + return stamp( + graph, + graph.nodes, + graph.edges.filter((edge) => edge.id !== edgeId), + at, + ); +} + +export function findNodesByType( + graph: BrainGraph, + type: BrainGraphNodeType, +): BrainGraphNode[] { + return graph.nodes.filter((node) => node.type === type); +} + +export function neighbors( + graph: BrainGraph, + nodeId: string, + options: GraphTraversalOptions = {}, +): BrainGraphNode[] { + requireNode(graph, nodeId); + const respectDirection = options.respectDirection ?? false; + const ids = new Set(); + + for (const edge of graph.edges) { + const adjacent = adjacentNodeId(edge, nodeId, respectDirection); + if (adjacent) ids.add(adjacent); + } + + return graph.nodes.filter((node) => ids.has(node.id)); +} + +export function shortestPath( + graph: BrainGraph, + startNodeId: string, + endNodeId: string, + options: GraphTraversalOptions = {}, +): string[] | null { + requireNode(graph, startNodeId); + requireNode(graph, endNodeId); + + if (startNodeId === endNodeId) return [startNodeId]; + + const respectDirection = options.respectDirection ?? false; + const queue: string[] = [startNodeId]; + const previous = new Map([[startNodeId, null]]); + + while (queue.length > 0) { + const current = queue.shift()!; + + for (const edge of graph.edges) { + const next = adjacentNodeId(edge, current, respectDirection); + if (!next || previous.has(next)) continue; + + previous.set(next, current); + + if (next === endNodeId) { + const path: string[] = []; + let cursor: string | null = endNodeId; + + while (cursor) { + path.push(cursor); + cursor = previous.get(cursor) ?? null; + } + + return path.reverse(); + } + + queue.push(next); + } + } + + return null; +} + +export function kHopNodeIds( + graph: BrainGraph, + seedNodeIds: string[], + hops: number, + options: GraphTraversalOptions = {}, +): Set { + const visited = new Set(); + let frontier = new Set(); + + for (const seed of seedNodeIds) { + requireNode(graph, seed); + visited.add(seed); + frontier.add(seed); + } + + for (let depth = 0; depth < hops; depth += 1) { + const nextFrontier = new Set(); + + for (const nodeId of frontier) { + for (const node of neighbors(graph, nodeId, options)) { + if (!visited.has(node.id)) { + visited.add(node.id); + nextFrontier.add(node.id); + } + } + } + + frontier = nextFrontier; + if (frontier.size === 0) break; + } + + return visited; +} + +export function subgraphByNodeIds( + graph: BrainGraph, + nodeIds: Iterable, +): BrainGraph { + const included = new Set(nodeIds); + + return BrainGraphSchema.parse({ + ...graph, + nodes: graph.nodes.filter((node) => included.has(node.id)), + edges: graph.edges.filter( + (edge) => + included.has(edge.source) && included.has(edge.target), + ), + }); +} + +export function kHopSubgraph( + graph: BrainGraph, + seedNodeIds: string[], + hops: number, + options: GraphTraversalOptions = {}, +): BrainGraph { + return subgraphByNodeIds( + graph, + kHopNodeIds(graph, seedNodeIds, hops, options), + ); +} + +export function findContradictionEdges( + graph: BrainGraph, +): BrainGraphEdge[] { + return graph.edges.filter((edge) => edge.type === 'contradicts'); +} + +export function mergeNodes( + graph: BrainGraph, + canonicalNodeId: string, + duplicateNodeIds: string[], + at?: string, +): BrainGraph { + const canonical = requireNode(graph, canonicalNodeId); + const duplicates = new Set( + duplicateNodeIds.filter((id) => id !== canonicalNodeId), + ); + + for (const duplicateId of duplicates) { + requireNode(graph, duplicateId); + } + + const priorMerged = Array.isArray(canonical.metadata.mergedNodeIds) + ? canonical.metadata.mergedNodeIds.filter( + (value): value is string => typeof value === 'string', + ) + : []; + + const mergedNode = BrainGraphNodeSchema.parse({ + ...canonical, + metadata: { + ...canonical.metadata, + mergedNodeIds: [...new Set([...priorMerged, ...duplicates])], + }, + version: canonical.version + 1, + }); + + const nodes = graph.nodes + .filter((node) => !duplicates.has(node.id)) + .map((node) => + node.id === canonicalNodeId ? mergedNode : node, + ); + + const rewired = graph.edges.map((edge) => ({ + ...edge, + source: duplicates.has(edge.source) + ? canonicalNodeId + : edge.source, + target: duplicates.has(edge.target) + ? canonicalNodeId + : edge.target, + })); + + return stamp(graph, nodes, dedupeEdges(rewired), at); +} + +export function graphStats(graph: BrainGraph) { + const byNodeType = new Map(); + const byEdgeType = new Map(); + + for (const node of graph.nodes) { + byNodeType.set(node.type, (byNodeType.get(node.type) ?? 0) + 1); + } + + for (const edge of graph.edges) { + byEdgeType.set(edge.type, (byEdgeType.get(edge.type) ?? 0) + 1); + } + + return { + nodeCount: graph.nodes.length, + edgeCount: graph.edges.length, + byNodeType: Object.fromEntries(byNodeType), + byEdgeType: Object.fromEntries(byEdgeType), + }; +} diff --git a/lib/brain/graph-schema.ts b/lib/brain/graph-schema.ts new file mode 100644 index 00000000..56ce8584 --- /dev/null +++ b/lib/brain/graph-schema.ts @@ -0,0 +1,269 @@ +import { z } from 'zod'; + +import { + AuditStampSchema, + ContextEnvelopeSchema, + EpistemicStateSchema, + ErrorClassSchema, + GovernanceEnvelopeSchema, + ProvenanceRefSchema, + TimestampSchema, + UnitIntervalSchema, +} from '@/lib/brain/core-schema'; + +import { + MemoryTraceSchema, +} from '@/lib/brain/memory-schema'; + +export const BrainGraphNodeTypeSchema = z.enum([ + 'brain', + 'department', + 'agent', + 'human', + 'goal', + 'task', + 'workflow', + 'policy', + 'sop', + 'tool', + 'provider', + 'dataset', + 'source', + 'evidence', + 'fact', + 'interpretation', + 'assumption', + 'thesis', + 'hypothesis', + 'question', + 'prediction', + 'counterfactual', + 'concept', + 'event', + 'experience', + 'decision', + 'outcome', + 'error', + 'lesson_candidate', + 'validated_lesson', + 'post_mortem', + 'asset', + 'instrument', + 'portfolio', + 'position', + 'proposal', + 'risk_ticket', + 'metric', + 'alert', +]); + +export const BrainGraphNodeStatusSchema = z.enum([ + 'planned', + 'pending', + 'active', + 'validated', + 'rejected', + 'invalidated', + 'superseded', + 'archived', + 'closed', +]); + +export const BrainGraphEdgeTypeSchema = z.enum([ + 'contains', + 'belongs_to', + 'reports_to', + 'supervises', + 'owns', + 'assigned_to', + 'created_by', + 'produced_by', + 'proposed_by', + 'reviewed_by', + 'approved_by', + 'rejected_by', + 'part_of', + 'depends_on', + 'precedes', + 'triggers', + 'observed_in', + 'references', + 'based_on', + 'supports', + 'contradicts', + 'invalidates', + 'corrects', + 'supersedes', + 'derived_from', + 'summarizes', + 'learned_from', + 'validated_by', + 'generalizes_to', + 'failed_because', + 'causes', + 'contributes_to', + 'resulted_in', + 'mitigates', + 'predicts', + 'tests', + 'explains', + 'concerns', + 'affects', + 'exposed_to', + 'benchmarked_against', + 'measured_by', + 'is_a', + 'instance_of', + 'similar_to', + 'related_to', + 'shares_memory_with', + 'retrieved_with', +]); + +export const BrainGraphEdgeStatusSchema = z.enum([ + 'active', + 'superseded', + 'archived', +]); + +export const BrainGraphNodeSchema = z.object({ + id: z.string().min(1), + type: BrainGraphNodeTypeSchema, + label: z.string().min(1), + summary: z.string().default(''), + content: z.string().default(''), + rationaleSummary: z.string().default(''), + status: BrainGraphNodeStatusSchema.default('active'), + canonicalKey: z.string().min(1).optional(), + tags: z.array(z.string().min(1)).default([]), + keywords: z.array(z.string().min(1)).default([]), + context: ContextEnvelopeSchema, + epistemic: EpistemicStateSchema.optional(), + errorClass: ErrorClassSchema.optional(), + memory: MemoryTraceSchema.optional(), + governance: GovernanceEnvelopeSchema, + audit: AuditStampSchema, + version: z.number().int().positive().default(1), + metadata: z.record(z.unknown()).default({}), +}); + +export const BrainGraphNodePatchSchema = + BrainGraphNodeSchema.partial().omit({ id: true }); + +export const BrainGraphEdgeSchema = z.object({ + id: z.string().min(1), + source: z.string().min(1), + target: z.string().min(1), + type: BrainGraphEdgeTypeSchema, + directed: z.boolean().default(true), + strength: UnitIntervalSchema.default(1), + confidence: UnitIntervalSchema.optional(), + status: BrainGraphEdgeStatusSchema.default('active'), + label: z.string().optional(), + context: ContextEnvelopeSchema, + provenance: z.array(ProvenanceRefSchema).default([]), + validFrom: TimestampSchema.optional(), + validUntil: TimestampSchema.optional(), + metadata: z.record(z.unknown()).default({}), +}); + +export const BrainGraphSchema = z + .object({ + schemaVersion: z.literal(1), + graphId: z.string().min(1), + revision: z.number().int().min(0).default(0), + generatedAt: TimestampSchema, + nodes: z.array(BrainGraphNodeSchema), + edges: z.array(BrainGraphEdgeSchema), + metadata: z.record(z.unknown()).default({}), + }) + .superRefine((graph, ctx) => { + const nodeIds = new Set(); + + graph.nodes.forEach((node, index) => { + if (nodeIds.has(node.id)) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['nodes', index, 'id'], + message: `Duplicate graph node id: ${node.id}`, + }); + } + nodeIds.add(node.id); + }); + + const edgeIds = new Set(); + const semanticEdges = new Set(); + + graph.edges.forEach((edge, index) => { + if (edgeIds.has(edge.id)) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['edges', index, 'id'], + message: `Duplicate graph edge id: ${edge.id}`, + }); + } + edgeIds.add(edge.id); + + if (!nodeIds.has(edge.source)) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['edges', index, 'source'], + message: `Unknown graph source node: ${edge.source}`, + }); + } + + if (!nodeIds.has(edge.target)) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['edges', index, 'target'], + message: `Unknown graph target node: ${edge.target}`, + }); + } + + if (edge.source === edge.target) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['edges', index], + message: `Self-referential graph edge is not allowed: ${edge.id}`, + }); + } + + if ( + edge.validFrom && + edge.validUntil && + Date.parse(edge.validUntil) < Date.parse(edge.validFrom) + ) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['edges', index, 'validUntil'], + message: 'validUntil cannot be earlier than validFrom', + }); + } + + const endpoints = edge.directed + ? `${edge.source}->${edge.target}` + : [edge.source, edge.target].sort().join('<->'); + + const semanticKey = `${edge.type}|${endpoints}|${edge.status}`; + + if (semanticEdges.has(semanticKey)) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['edges', index], + message: `Duplicate semantic edge: ${semanticKey}`, + }); + } + semanticEdges.add(semanticKey); + }); + }); + +export type BrainGraphNodeType = z.infer; +export type BrainGraphNodeStatus = z.infer; +export type BrainGraphEdgeType = z.infer; +export type BrainGraphNode = z.infer; +export type BrainGraphNodeInput = z.input; +export type BrainGraphNodePatchInput = z.input; +export type BrainGraphEdge = z.infer; +export type BrainGraphEdgeInput = z.input; +export type BrainGraph = z.infer; +export type BrainGraphInput = z.input; diff --git a/lib/brain/index.ts b/lib/brain/index.ts new file mode 100644 index 00000000..ad44d442 --- /dev/null +++ b/lib/brain/index.ts @@ -0,0 +1,11 @@ +export * from '@/lib/brain/core-schema'; +export * from '@/lib/brain/memory-schema'; +export * from '@/lib/brain/graph-schema'; +export * from '@/lib/brain/memory-dynamics'; +export * from '@/lib/brain/graph-ops'; +export * from '@/lib/brain/retrieval'; +export * from '@/lib/brain/brain-health'; +export * from '@/lib/brain/reasoning'; +export * from '@/lib/brain/learning'; +export * from '@/lib/brain/events'; +export * from '@/lib/brain/graph-foundation'; diff --git a/lib/brain/learning.ts b/lib/brain/learning.ts new file mode 100644 index 00000000..31ad5430 --- /dev/null +++ b/lib/brain/learning.ts @@ -0,0 +1,175 @@ +import type { + BrainGraph, + BrainGraphNode, +} from '@/lib/brain/graph-schema'; + +import { + requireNode, +} from '@/lib/brain/graph-ops'; + +import { + decayedRetention, +} from '@/lib/brain/memory-dynamics'; + +function jaccard( + left: Iterable, + right: Iterable, +): number { + const a = new Set(left); + const b = new Set(right); + + if (a.size === 0 && b.size === 0) return 0; + + let intersection = 0; + for (const value of a) { + if (b.has(value)) intersection += 1; + } + + const union = new Set([...a, ...b]).size; + return union === 0 ? 0 : intersection / union; +} + +function contextTokens(node: BrainGraphNode): string[] { + return [ + ...node.context.departmentIds.map((x) => `department:${x}`), + ...node.context.agentIds.map((x) => `agent:${x}`), + ...node.context.assetIds.map((x) => `asset:${x}`), + ...node.context.instrumentIds.map((x) => `instrument:${x}`), + ...node.context.portfolioIds.map((x) => `portfolio:${x}`), + ...node.context.horizons.map((x) => `horizon:${x}`), + ...node.context.marketRegimes.map((x) => `regime:${x}`), + ...node.context.scenarios.map((x) => `scenario:${x}`), + ...node.tags.map((x) => `tag:${x}`), + ]; +} + +export function findConsolidationCandidates( + graph: BrainGraph, +): BrainGraphNode[] { + return graph.nodes.filter( + (node) => + node.memory?.stage === 'lesson_candidate' && + node.status !== 'archived' && + node.status !== 'superseded', + ); +} + +export function findProspectiveMemories( + graph: BrainGraph, +): BrainGraphNode[] { + return graph.nodes.filter( + (node) => + node.memory?.system === 'prospective' && + ['planned', 'pending', 'active'].includes(node.status), + ); +} + +export function findArchiveCandidates( + graph: BrainGraph, + now: string, + retentionThreshold: number, +): BrainGraphNode[] { + if ( + !Number.isFinite(retentionThreshold) || + retentionThreshold < 0 || + retentionThreshold > 1 + ) { + throw new Error('retentionThreshold must be between 0 and 1'); + } + + return graph.nodes.filter((node) => { + if ( + !node.memory || + node.memory.retentionLock || + node.memory.system === 'structural' || + node.status === 'archived' + ) { + return false; + } + + return decayedRetention(node, now) <= retentionThreshold; + }); +} + +export type AnalogyCandidate = { + node: BrainGraphNode; + score: number; + sharedContext: number; + sameType: boolean; + sameMemorySystem: boolean; +}; + +export function findAnalogies( + graph: BrainGraph, + nodeId: string, + options: { + limit?: number; + minimumScore?: number; + } = {}, +): AnalogyCandidate[] { + const source = requireNode(graph, nodeId); + const limit = options.limit ?? 10; + const minimumScore = options.minimumScore ?? 0.15; + const sourceContext = contextTokens(source); + + return graph.nodes + .filter((candidate) => candidate.id !== source.id) + .map((candidate) => { + const sharedContext = jaccard( + sourceContext, + contextTokens(candidate), + ); + + const sameType = candidate.type === source.type; + const sameMemorySystem = + candidate.memory?.system !== undefined && + candidate.memory.system === source.memory?.system; + + const score = Math.min( + 1, + sharedContext * 0.7 + + (sameType ? 0.2 : 0) + + (sameMemorySystem ? 0.1 : 0), + ); + + return { + node: candidate, + score, + sharedContext, + sameType, + sameMemorySystem, + }; + }) + .filter((candidate) => candidate.score >= minimumScore) + .sort( + (a, b) => + b.score - a.score || + a.node.label.localeCompare(b.node.label), + ) + .slice(0, limit); +} + +export function repeatedErrorPatterns( + graph: BrainGraph, +) { + const groups = new Map(); + + for (const node of graph.nodes) { + if (node.type !== 'error' || !node.errorClass) continue; + + const context = [ + node.errorClass, + ...node.context.assetIds.map((id) => `asset:${id}`), + ...node.context.marketRegimes.map((id) => `regime:${id}`), + ...node.context.horizons.map((id) => `horizon:${id}`), + ].join('|'); + + const ids = groups.get(context) ?? []; + ids.push(node.id); + groups.set(context, ids); + } + + return [...groups.entries()] + .filter(([, ids]) => ids.length >= 2) + .map(([patternKey, nodeIds]) => ({ patternKey, nodeIds })); +} diff --git a/lib/brain/memory-dynamics.ts b/lib/brain/memory-dynamics.ts new file mode 100644 index 00000000..7af7d470 --- /dev/null +++ b/lib/brain/memory-dynamics.ts @@ -0,0 +1,224 @@ +import type { + BrainGraphNode, +} from '@/lib/brain/graph-schema'; + +import type { + CognitivePolicy, + MemoryStage, +} from '@/lib/brain/memory-schema'; + +const ALLOWED_TRANSITIONS: Record = { + structural: ['structural', 'archived'], + working: ['working', 'interpreted_experience', 'archived'], + raw_experience: ['raw_experience', 'interpreted_experience', 'archived'], + interpreted_experience: [ + 'interpreted_experience', + 'lesson_candidate', + 'archived', + ], + lesson_candidate: [ + 'lesson_candidate', + 'validated_lesson', + 'archived', + ], + validated_lesson: [ + 'validated_lesson', + 'consolidated', + 'superseded', + 'archived', + ], + consolidated: [ + 'consolidated', + 'superseded', + 'archived', + ], + superseded: ['superseded', 'archived'], + archived: ['archived'], +}; + +function clamp01(value: number): number { + return Math.max(0, Math.min(1, value)); +} + +function parseTime(value: string): number { + const parsed = Date.parse(value); + if (!Number.isFinite(parsed)) { + throw new Error(`Invalid timestamp: ${value}`); + } + return parsed; +} + +export function compositeSalience( + node: BrainGraphNode, +): number { + const salience = node.memory?.salience; + if (!salience) return 0; + + const dimensions = [ + salience.novelty, + salience.surprise, + salience.materiality, + salience.urgency, + salience.riskImpact, + salience.expectedUtility, + ]; + + return dimensions.reduce((sum, value) => sum + value, 0) / + dimensions.length; +} + +export function decayedRetention( + node: BrainGraphNode, + now: string, +): number { + const memory = node.memory; + if (!memory) return 1; + + if ( + memory.retentionLock || + !memory.decayHalfLifeHours || + !memory.lastReinforcedAt + ) { + return memory.retentionStrength; + } + + const elapsedHours = Math.max( + 0, + (parseTime(now) - parseTime(memory.lastReinforcedAt)) / + (1000 * 60 * 60), + ); + + const decayFactor = Math.pow( + 0.5, + elapsedHours / memory.decayHalfLifeHours, + ); + + return clamp01(memory.retentionStrength * decayFactor); +} + +export function touchMemoryNode( + node: BrainGraphNode, + at: string, + activationBoost = 0.25, +): BrainGraphNode { + if (!node.memory) return node; + + const activation = clamp01( + node.memory.activation + + activationBoost * (1 - node.memory.activation), + ); + + return { + ...node, + memory: { + ...node.memory, + activation, + accessCount: node.memory.accessCount + 1, + lastAccessedAt: at, + }, + }; +} + +export function reinforceMemoryNode( + node: BrainGraphNode, + at: string, + amount = 0.1, +): BrainGraphNode { + if (!node.memory) return node; + + return { + ...node, + memory: { + ...node.memory, + retentionStrength: clamp01( + node.memory.retentionStrength + amount, + ), + rehearsalCount: node.memory.rehearsalCount + 1, + lastReinforcedAt: at, + }, + }; +} + +export function transitionMemoryStage( + node: BrainGraphNode, + targetStage: MemoryStage, +): BrainGraphNode { + if (!node.memory) { + throw new Error(`Node ${node.id} does not carry a memory trace`); + } + + const current = node.memory.stage; + + if (!ALLOWED_TRANSITIONS[current].includes(targetStage)) { + throw new Error( + `Invalid memory transition for ${node.id}: ${current} -> ${targetStage}`, + ); + } + + return { + ...node, + memory: { + ...node.memory, + stage: targetStage, + }, + }; +} + +export type ConsolidationEvidence = { + observations: number; + independentSources: number; + outcomeEvaluations: number; + confidence: number; +}; + +export type ConsolidationAssessment = { + ready: boolean; + reasons: string[]; +}; + +export function assessConsolidationCandidate( + node: BrainGraphNode, + policy: CognitivePolicy, + evidence: ConsolidationEvidence, +): ConsolidationAssessment { + const reasons: string[] = []; + + if (!node.memory) { + reasons.push('node_has_no_memory_trace'); + } else if (node.memory.stage !== 'lesson_candidate') { + reasons.push('node_is_not_a_lesson_candidate'); + } + + if ( + evidence.observations < + policy.consolidation.minimumObservations + ) { + reasons.push('insufficient_observations'); + } + + if ( + evidence.independentSources < + policy.consolidation.minimumIndependentSources + ) { + reasons.push('insufficient_independent_sources'); + } + + if ( + evidence.outcomeEvaluations < + policy.consolidation.minimumOutcomeEvaluations + ) { + reasons.push('insufficient_outcome_evaluations'); + } + + if ( + evidence.confidence < + policy.consolidation.minimumConfidence + ) { + reasons.push('confidence_below_policy_threshold'); + } + + return { + ready: reasons.length === 0, + reasons, + }; +} diff --git a/lib/brain/memory-schema.ts b/lib/brain/memory-schema.ts new file mode 100644 index 00000000..14a9fdcb --- /dev/null +++ b/lib/brain/memory-schema.ts @@ -0,0 +1,129 @@ +import { z } from 'zod'; + +import { + ContextEnvelopeSchema, + NonNegativeFiniteSchema, + PositiveFiniteSchema, + TimestampSchema, + UnitIntervalSchema, +} from '@/lib/brain/core-schema'; + +export const MemorySystemSchema = z.enum([ + 'structural', + 'working', + 'episodic', + 'semantic', + 'procedural', + 'prospective', + 'metacognitive', +]); + +export const MemoryStageSchema = z.enum([ + 'structural', + 'working', + 'raw_experience', + 'interpreted_experience', + 'lesson_candidate', + 'validated_lesson', + 'consolidated', + 'superseded', + 'archived', +]); + +export const SalienceDimensionsSchema = z + .object({ + novelty: UnitIntervalSchema.default(0), + surprise: UnitIntervalSchema.default(0), + materiality: UnitIntervalSchema.default(0), + urgency: UnitIntervalSchema.default(0), + riskImpact: UnitIntervalSchema.default(0), + expectedUtility: UnitIntervalSchema.default(0), + }) + .default({}); + +export const MemoryTraceSchema = z.object({ + system: MemorySystemSchema, + stage: MemoryStageSchema, + + salience: SalienceDimensionsSchema, + + activation: UnitIntervalSchema.default(0), + retentionStrength: UnitIntervalSchema.default(1), + consolidationScore: UnitIntervalSchema.default(0), + + accessCount: z.number().int().min(0).default(0), + rehearsalCount: z.number().int().min(0).default(0), + + lastAccessedAt: TimestampSchema.optional(), + lastReinforcedAt: TimestampSchema.optional(), + + decayHalfLifeHours: PositiveFiniteSchema.optional(), + + retentionLock: z.boolean().default(false), + pendingReview: z.boolean().default(false), +}); + +export const ConsolidationPolicySchema = z.object({ + minimumObservations: z.number().int().positive(), + minimumIndependentSources: z.number().int().nonnegative(), + minimumOutcomeEvaluations: z.number().int().nonnegative(), + minimumConfidence: UnitIntervalSchema, + requireHumanApprovalForValidatedLessons: z.boolean(), +}); + +export const CognitivePolicySchema = z.object({ + workingMemoryCapacity: z.number().int().positive(), + defaultRetrievalLimit: z.number().int().positive(), + maxGraphHops: z.number().int().min(0), + activationDecayPerHop: UnitIntervalSchema, + minimumEdgeStrengthForSpread: UnitIntervalSchema, + archiveBelowRetentionStrength: UnitIntervalSchema, + consolidation: ConsolidationPolicySchema, +}); + +export const WorkingMemoryFrameSchema = z + .object({ + id: z.string().min(1), + purpose: z.string().min(1), + focusNodeIds: z.array(z.string().min(1)).default([]), + cueNodeIds: z.array(z.string().min(1)).default([]), + goalNodeIds: z.array(z.string().min(1)).default([]), + suppressedNodeIds: z.array(z.string().min(1)).default([]), + capacity: z.number().int().positive(), + attentionBudget: NonNegativeFiniteSchema.default(1), + context: ContextEnvelopeSchema, + createdAt: TimestampSchema, + expiresAt: TimestampSchema.optional(), + }) + .superRefine((frame, ctx) => { + const uniqueWorkingSet = new Set([ + ...frame.focusNodeIds, + ...frame.cueNodeIds, + ...frame.goalNodeIds, + ]); + + if (uniqueWorkingSet.size > frame.capacity) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['capacity'], + message: 'Working-memory frame exceeds its declared capacity', + }); + } + + if ( + frame.expiresAt && + Date.parse(frame.expiresAt) < Date.parse(frame.createdAt) + ) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ['expiresAt'], + message: 'expiresAt cannot be earlier than createdAt', + }); + } + }); + +export type MemorySystem = z.infer; +export type MemoryStage = z.infer; +export type MemoryTrace = z.infer; +export type CognitivePolicy = z.infer; +export type WorkingMemoryFrame = z.infer; diff --git a/lib/brain/reasoning.ts b/lib/brain/reasoning.ts new file mode 100644 index 00000000..f81d549c --- /dev/null +++ b/lib/brain/reasoning.ts @@ -0,0 +1,227 @@ +import type { + BrainGraph, + BrainGraphEdge, + BrainGraphNode, +} from '@/lib/brain/graph-schema'; + +import { + requireNode, +} from '@/lib/brain/graph-ops'; + +const CAUSAL_EDGE_TYPES = new Set([ + 'causes', + 'contributes_to', + 'resulted_in', + 'mitigates', + 'failed_because', + 'explains', +]); + +function evidenceWeight( + graph: BrainGraph, + edge: BrainGraphEdge, +): number { + const source = graph.nodes.find( + (node) => node.id === edge.source, + ); + + return ( + edge.strength * + (edge.confidence ?? 1) * + (source?.epistemic?.confidence ?? 0.5) + ); +} + +export function evidenceBalance( + graph: BrainGraph, + targetNodeId: string, +) { + requireNode(graph, targetNodeId); + + const supporting = graph.edges.filter( + (edge) => + edge.target === targetNodeId && + edge.type === 'supports' && + edge.status === 'active', + ); + + const contradicting = graph.edges.filter( + (edge) => + edge.target === targetNodeId && + edge.type === 'contradicts' && + edge.status === 'active', + ); + + const supportScore = supporting.reduce( + (sum, edge) => sum + evidenceWeight(graph, edge), + 0, + ); + + const contradictionScore = contradicting.reduce( + (sum, edge) => sum + evidenceWeight(graph, edge), + 0, + ); + + const total = supportScore + contradictionScore; + + return { + targetNodeId, + supportScore, + contradictionScore, + normalizedSupport: + total === 0 ? 0 : supportScore / total, + normalizedContradiction: + total === 0 ? 0 : contradictionScore / total, + netEvidence: supportScore - contradictionScore, + supportingNodeIds: supporting.map((edge) => edge.source), + contradictingNodeIds: contradicting.map((edge) => edge.source), + }; +} + +export function causalNeighborhood( + graph: BrainGraph, + nodeId: string, + direction: 'upstream' | 'downstream', + maxHops = 4, +): Set { + requireNode(graph, nodeId); + + const visited = new Set([nodeId]); + let frontier = new Set([nodeId]); + + for (let depth = 0; depth < maxHops; depth += 1) { + const nextFrontier = new Set(); + + for (const current of frontier) { + for (const edge of graph.edges) { + if ( + edge.status !== 'active' || + !CAUSAL_EDGE_TYPES.has(edge.type) + ) { + continue; + } + + const next = + direction === 'upstream' + ? edge.target === current + ? edge.source + : null + : edge.source === current + ? edge.target + : null; + + if (next && !visited.has(next)) { + visited.add(next); + nextFrontier.add(next); + } + } + } + + frontier = nextFrontier; + if (frontier.size === 0) break; + } + + return visited; +} + +export function findUnresolvedContradictions( + graph: BrainGraph, +): BrainGraphEdge[] { + const inactive = new Set([ + 'superseded', + 'invalidated', + 'archived', + 'rejected', + ]); + + return graph.edges.filter((edge) => { + if ( + edge.type !== 'contradicts' || + edge.status !== 'active' + ) { + return false; + } + + const source = graph.nodes.find( + (node) => node.id === edge.source, + ); + const target = graph.nodes.find( + (node) => node.id === edge.target, + ); + + return ( + source !== undefined && + target !== undefined && + !inactive.has(source.status) && + !inactive.has(target.status) + ); + }); +} + +export function findOpenQuestions( + graph: BrainGraph, +): BrainGraphNode[] { + return graph.nodes.filter((node) => { + if ( + node.type !== 'question' || + node.status === 'closed' || + node.status === 'archived' + ) { + return false; + } + + return !graph.edges.some( + (edge) => + edge.status === 'active' && + edge.target === node.id && + ['supports', 'explains', 'validated_by'].includes(edge.type), + ); + }); +} + +export function findKnowledgeGaps( + graph: BrainGraph, +) { + const ungroundedHypothesisIds = graph.nodes + .filter((node) => node.type === 'hypothesis') + .filter( + (node) => + !graph.edges.some( + (edge) => + edge.status === 'active' && + (edge.source === node.id || edge.target === node.id) && + ['supports', 'contradicts', 'based_on', 'tests'].includes( + edge.type, + ), + ), + ) + .map((node) => node.id); + + const sourceLessFactIds = graph.nodes + .filter( + (node) => + node.type === 'fact' && + (node.epistemic?.provenance.length ?? 0) === 0, + ) + .map((node) => node.id); + + const decisionWithoutBasisIds = graph.nodes + .filter((node) => node.type === 'decision') + .filter( + (node) => + !graph.edges.some( + (edge) => + edge.status === 'active' && + edge.source === node.id && + edge.type === 'based_on', + ), + ) + .map((node) => node.id); + + return { + openQuestionIds: findOpenQuestions(graph).map((node) => node.id), + ungroundedHypothesisIds, + sourceLessFactIds, + decisionWithoutBasisIds, + }; +} diff --git a/lib/brain/retrieval.ts b/lib/brain/retrieval.ts new file mode 100644 index 00000000..81f26031 --- /dev/null +++ b/lib/brain/retrieval.ts @@ -0,0 +1,358 @@ +import { z } from 'zod'; + +import { + EpistemicKindSchema, + TimestampSchema, + UnitIntervalSchema, +} from '@/lib/brain/core-schema'; + +import { + BrainGraphNodeTypeSchema, + type BrainGraph, + type BrainGraphEdge, + type BrainGraphNode, +} from '@/lib/brain/graph-schema'; + +import { + MemorySystemSchema, + WorkingMemoryFrameSchema, + type WorkingMemoryFrame, +} from '@/lib/brain/memory-schema'; + +import { + compositeSalience, + decayedRetention, +} from '@/lib/brain/memory-dynamics'; + +export const BrainRetrievalQuerySchema = z.object({ + text: z.string().default(''), + nodeTypes: z.array(BrainGraphNodeTypeSchema).default([]), + memorySystems: z.array(MemorySystemSchema).default([]), + epistemicKinds: z.array(EpistemicKindSchema).default([]), + departmentIds: z.array(z.string().min(1)).default([]), + agentIds: z.array(z.string().min(1)).default([]), + assetIds: z.array(z.string().min(1)).default([]), + tags: z.array(z.string().min(1)).default([]), + seedNodeIds: z.array(z.string().min(1)).default([]), + minConfidence: UnitIntervalSchema.optional(), + includeArchived: z.boolean().default(false), + includeSuperseded: z.boolean().default(false), + maxHops: z.number().int().min(0).max(12).default(3), + limit: z.number().int().positive().max(200).default(20), + asOf: TimestampSchema.optional(), +}); + +export const BrainRetrievalWeightsSchema = z.object({ + text: z.number().finite().min(0), + salience: z.number().finite().min(0), + activation: z.number().finite().min(0), + confidence: z.number().finite().min(0), + retention: z.number().finite().min(0), + recency: z.number().finite().min(0), + graphProximity: z.number().finite().min(0), +}); + +export const DEFAULT_RETRIEVAL_WEIGHTS = { + text: 0.30, + salience: 0.13, + activation: 0.13, + confidence: 0.13, + retention: 0.10, + recency: 0.08, + graphProximity: 0.13, +} as const; + +export type BrainRetrievalQuery = z.infer; +export type BrainRetrievalQueryInput = z.input; +export type BrainRetrievalWeights = z.infer; + +export type BrainRetrievalScoreBreakdown = { + text: number; + salience: number; + activation: number; + confidence: number; + retention: number; + recency: number; + graphProximity: number; +}; + +export type BrainRetrievalResult = { + node: BrainGraphNode; + score: number; + breakdown: BrainRetrievalScoreBreakdown; + reasons: string[]; +}; + +function clamp01(value: number): number { + return Math.max(0, Math.min(1, value)); +} + +function tokenize(text: string): Set { + return new Set( + text + .normalize('NFKD') + .toLowerCase() + .replace(/[^\p{L}\p{N}]+/gu, ' ') + .split(/\s+/) + .map((token) => token.trim()) + .filter((token) => token.length >= 2), + ); +} + +function lexicalScore(node: BrainGraphNode, queryText: string): number { + const queryTokens = tokenize(queryText); + if (queryTokens.size === 0) return 0; + + const haystack = tokenize( + [ + node.label, + node.summary, + node.content, + ...node.tags, + ...node.keywords, + ].join(' '), + ); + + let matches = 0; + for (const token of queryTokens) { + if (haystack.has(token)) matches += 1; + } + + return matches / queryTokens.size; +} + +function recencyScore(node: BrainGraphNode, now: string): number { + const updatedAt = node.audit.updatedAt ?? node.audit.createdAt; + if (!updatedAt) return 0.5; + + const ageDays = Math.max( + 0, + (Date.parse(now) - Date.parse(updatedAt)) / + (1000 * 60 * 60 * 24), + ); + + return Math.exp(-ageDays / 90); +} + +function contextMatches( + node: BrainGraphNode, + query: BrainRetrievalQuery, +): boolean { + const overlaps = (wanted: string[], actual: string[]) => + wanted.length === 0 || wanted.some((value) => actual.includes(value)); + + return ( + overlaps(query.departmentIds, node.context.departmentIds) && + overlaps(query.agentIds, node.context.agentIds) && + overlaps(query.assetIds, node.context.assetIds) && + overlaps(query.tags, [...node.tags, ...node.context.tags]) + ); +} + +function edgeNeighbor(edge: BrainGraphEdge, nodeId: string): string | null { + if (edge.source === nodeId) return edge.target; + if (edge.target === nodeId) return edge.source; + return null; +} + +export function spreadActivation( + graph: BrainGraph, + seedNodeIds: string[], + maxHops: number, + decayPerHop = 0.65, +): Map { + const activation = new Map(); + const queue: Array<{ + nodeId: string; + value: number; + depth: number; + }> = []; + + for (const seedNodeId of seedNodeIds) { + if (!graph.nodes.some((node) => node.id === seedNodeId)) continue; + + activation.set(seedNodeId, 1); + queue.push({ nodeId: seedNodeId, value: 1, depth: 0 }); + } + + while (queue.length > 0) { + const current = queue.shift()!; + if (current.depth >= maxHops) continue; + + for (const edge of graph.edges) { + if (edge.status !== 'active') continue; + + const nextNodeId = edgeNeighbor(edge, current.nodeId); + if (!nextNodeId) continue; + + const nextActivation = + current.value * + decayPerHop * + edge.strength * + (edge.confidence ?? 1); + + const previous = activation.get(nextNodeId) ?? 0; + if (nextActivation <= previous) continue; + + activation.set(nextNodeId, clamp01(nextActivation)); + queue.push({ + nodeId: nextNodeId, + value: nextActivation, + depth: current.depth + 1, + }); + } + } + + return activation; +} + +function matchesHardFilters( + node: BrainGraphNode, + query: BrainRetrievalQuery, +): boolean { + if (!query.includeArchived && node.status === 'archived') return false; + if (!query.includeSuperseded && node.status === 'superseded') return false; + + if ( + query.nodeTypes.length > 0 && + !query.nodeTypes.includes(node.type) + ) { + return false; + } + + if ( + query.memorySystems.length > 0 && + (!node.memory || !query.memorySystems.includes(node.memory.system)) + ) { + return false; + } + + if ( + query.epistemicKinds.length > 0 && + (!node.epistemic || !query.epistemicKinds.includes(node.epistemic.kind)) + ) { + return false; + } + + if ( + query.minConfidence !== undefined && + (node.epistemic?.confidence ?? 0) < query.minConfidence + ) { + return false; + } + + return contextMatches(node, query); +} + +function normalizedWeightedScore( + breakdown: BrainRetrievalScoreBreakdown, + weights: BrainRetrievalWeights, +): number { + const entries = Object.entries(weights) as Array< + [keyof BrainRetrievalWeights, number] + >; + + const totalWeight = entries.reduce((sum, [, weight]) => sum + weight, 0); + if (totalWeight <= 0) return 0; + + const weighted = entries.reduce( + (sum, [key, weight]) => sum + breakdown[key] * weight, + 0, + ); + + return clamp01(weighted / totalWeight); +} + +export function retrieveBrainGraph( + graph: BrainGraph, + queryInput: BrainRetrievalQueryInput, + options: { + now?: string; + weights?: BrainRetrievalWeights; + } = {}, +): BrainRetrievalResult[] { + const query = BrainRetrievalQuerySchema.parse(queryInput); + const weights = BrainRetrievalWeightsSchema.parse( + options.weights ?? DEFAULT_RETRIEVAL_WEIGHTS, + ); + const now = options.now ?? query.asOf ?? new Date().toISOString(); + + const graphActivation = spreadActivation( + graph, + query.seedNodeIds, + query.maxHops, + ); + + const results: BrainRetrievalResult[] = []; + + for (const node of graph.nodes) { + if (!matchesHardFilters(node, query)) continue; + + const breakdown: BrainRetrievalScoreBreakdown = { + text: lexicalScore(node, query.text), + salience: compositeSalience(node), + activation: Math.max( + node.memory?.activation ?? 0, + graphActivation.get(node.id) ?? 0, + ), + confidence: node.epistemic?.confidence ?? 0.5, + retention: decayedRetention(node, now), + recency: recencyScore(node, now), + graphProximity: graphActivation.get(node.id) ?? 0, + }; + + const score = normalizedWeightedScore(breakdown, weights); + const reasons: string[] = []; + + if (breakdown.text > 0) reasons.push('text_match'); + if (breakdown.graphProximity > 0) reasons.push('graph_proximity'); + if (breakdown.salience >= 0.5) reasons.push('high_salience'); + if (breakdown.confidence >= 0.75) reasons.push('high_confidence'); + if (breakdown.retention >= 0.75) reasons.push('strong_memory'); + + results.push({ node, score, breakdown, reasons }); + } + + return results + .sort( + (a, b) => + b.score - a.score || a.node.label.localeCompare(b.node.label), + ) + .slice(0, query.limit); +} + +export function buildWorkingMemoryFrame( + results: BrainRetrievalResult[], + input: { + id: string; + purpose: string; + capacity: number; + createdAt?: string; + expiresAt?: string; + cueNodeIds?: string[]; + goalNodeIds?: string[]; + suppressedNodeIds?: string[]; + }, +): WorkingMemoryFrame { + const cueNodeIds = input.cueNodeIds ?? []; + const goalNodeIds = input.goalNodeIds ?? []; + const reserved = new Set([...cueNodeIds, ...goalNodeIds]).size; + const focusCapacity = Math.max(0, input.capacity - reserved); + + return WorkingMemoryFrameSchema.parse({ + id: input.id, + purpose: input.purpose, + capacity: input.capacity, + focusNodeIds: results + .map((result) => result.node.id) + .filter((id) => !cueNodeIds.includes(id) && !goalNodeIds.includes(id)) + .slice(0, focusCapacity), + cueNodeIds, + goalNodeIds, + suppressedNodeIds: input.suppressedNodeIds ?? [], + attentionBudget: 1, + context: {}, + createdAt: input.createdAt ?? new Date().toISOString(), + expiresAt: input.expiresAt, + }); +} diff --git a/tests/brain-foundation.test.ts b/tests/brain-foundation.test.ts new file mode 100644 index 00000000..2b8e3a57 --- /dev/null +++ b/tests/brain-foundation.test.ts @@ -0,0 +1,143 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + buildFoundationBrainGraph, + STARTUP_BRAIN_NODE_ID, +} from '@/lib/brain/graph-foundation'; + +import { + BrainGraphSchema, +} from '@/lib/brain/graph-schema'; + +import { + openDb, + type FounderDb, +} from '@/lib/db'; + +import { + seedDatabase, +} from '@/lib/seed'; + +let db: FounderDb; + +afterEach(() => { + db?.close(); +}); + +describe('Startup Brain foundation graph', () => { + test('contains the brain, 3 departments and 19 agents', () => { + db = openDb(':memory:'); + seedDatabase(db); + + const graph = buildFoundationBrainGraph( + db.departments.all(), + db.agents.all(), + '2026-01-01T00:00:00.000Z', + ); + + expect(graph.nodes).toHaveLength(23); + expect(graph.edges).toHaveLength(38); + + expect( + graph.nodes.find( + (node) => node.id === STARTUP_BRAIN_NODE_ID, + ), + ).toMatchObject({ + type: 'brain', + label: 'Startup Brain', + }); + + expect( + graph.nodes.filter((node) => node.type === 'department'), + ).toHaveLength(3); + + expect( + graph.nodes.filter((node) => node.type === 'agent'), + ).toHaveLength(19); + }); + + test('contains structural information only', () => { + db = openDb(':memory:'); + seedDatabase(db); + + const graph = buildFoundationBrainGraph( + db.departments.all(), + db.agents.all(), + '2026-01-01T00:00:00.000Z', + ); + + const allowed = new Set(['brain', 'department', 'agent']); + + expect( + graph.nodes.every((node) => allowed.has(node.type)), + ).toBe(true); + + expect(graph.metadata.operationalMemoryIncluded).toBe(false); + }); + + test('every agent belongs to its department', () => { + db = openDb(':memory:'); + seedDatabase(db); + + const graph = buildFoundationBrainGraph( + db.departments.all(), + db.agents.all(), + '2026-01-01T00:00:00.000Z', + ); + + for (const agent of db.agents.all()) { + expect( + graph.edges.some( + (edge) => + edge.type === 'belongs_to' && + edge.source === agent.id && + edge.target === agent.departmentId, + ), + ).toBe(true); + } + }); + + test('full snapshot passes graph invariants', () => { + db = openDb(':memory:'); + seedDatabase(db); + + const graph = buildFoundationBrainGraph( + db.departments.all(), + db.agents.all(), + '2026-01-01T00:00:00.000Z', + ); + + expect(() => BrainGraphSchema.parse(graph)).not.toThrow(); + }); + + test('rejects dangling edges', () => { + const result = BrainGraphSchema.safeParse({ + schemaVersion: 1, + graphId: 'x', + revision: 0, + generatedAt: '2026-01-01T00:00:00.000Z', + nodes: [ + { + id: 'a', + type: 'concept', + label: 'A', + }, + ], + edges: [ + { + id: 'e1', + source: 'a', + target: 'missing', + type: 'related_to', + }, + ], + }); + + expect(result.success).toBe(false); + }); +}); diff --git a/tests/brain-ops.test.ts b/tests/brain-ops.test.ts new file mode 100644 index 00000000..8243374f --- /dev/null +++ b/tests/brain-ops.test.ts @@ -0,0 +1,142 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + addEdge, + addNode, + createEmptyBrainGraph, + kHopNodeIds, + mergeNodes, + removeNode, + shortestPath, +} from '@/lib/brain/graph-ops'; + +function concept(id: string, label = id) { + return { + id, + type: 'concept' as const, + label, + }; +} + +describe('Startup Brain graph operations', () => { + test('adds nodes and semantic edges safely', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, concept('a')); + graph = addNode(graph, concept('b')); + + graph = addEdge(graph, { + id: 'e1', + source: 'a', + target: 'b', + type: 'supports', + directed: true, + strength: 0.8, + }); + + expect(graph.nodes).toHaveLength(2); + expect(graph.edges).toHaveLength(1); + }); + + test('requires cascade before removing a connected node', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, concept('a')); + graph = addNode(graph, concept('b')); + + graph = addEdge(graph, { + id: 'e1', + source: 'a', + target: 'b', + type: 'related_to', + directed: false, + }); + + expect(() => removeNode(graph, 'a')).toThrow(); + + const removed = removeNode( + graph, + 'a', + { cascade: true }, + ); + + expect(removed.nodes).toHaveLength(1); + expect(removed.edges).toHaveLength(0); + }); + + test('finds paths and k-hop neighborhoods', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + for (const id of ['a', 'b', 'c']) { + graph = addNode(graph, concept(id)); + } + + graph = addEdge(graph, { + id: 'ab', + source: 'a', + target: 'b', + type: 'related_to', + directed: false, + }); + + graph = addEdge(graph, { + id: 'bc', + source: 'b', + target: 'c', + type: 'related_to', + directed: false, + }); + + expect(shortestPath(graph, 'a', 'c')).toEqual(['a', 'b', 'c']); + expect([...kHopNodeIds(graph, ['a'], 1)].sort()).toEqual(['a', 'b']); + }); + + test('merges duplicate nodes and rewires edges', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + for (const id of ['canonical', 'duplicate', 'other']) { + graph = addNode(graph, concept(id)); + } + + graph = addEdge(graph, { + id: 'duplicate-other', + source: 'duplicate', + target: 'other', + type: 'related_to', + directed: false, + }); + + const merged = mergeNodes( + graph, + 'canonical', + ['duplicate'], + ); + + expect( + merged.nodes.some((node) => node.id === 'duplicate'), + ).toBe(false); + + expect( + merged.edges.some( + (edge) => + edge.source === 'canonical' || edge.target === 'canonical', + ), + ).toBe(true); + }); +}); diff --git a/tests/brain-reasoning.test.ts b/tests/brain-reasoning.test.ts new file mode 100644 index 00000000..f3d6071d --- /dev/null +++ b/tests/brain-reasoning.test.ts @@ -0,0 +1,153 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + addEdge, + addNode, + createEmptyBrainGraph, +} from '@/lib/brain/graph-ops'; + +import { + evidenceBalance, + findKnowledgeGaps, + findUnresolvedContradictions, +} from '@/lib/brain/reasoning'; + +import { + findAnalogies, + repeatedErrorPatterns, +} from '@/lib/brain/learning'; + +function node( + id: string, + type: 'evidence' | 'thesis' | 'question' | 'error' | 'experience', + extra: Record = {}, +) { + return { + id, + type, + label: id, + ...extra, + }; +} + +describe('Startup Brain reasoning and learning', () => { + test('balances supporting and contradicting evidence', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, node('support', 'evidence', { + epistemic: { + kind: 'fact', + confidence: 0.9, + verification: 'verified', + temporal: {}, + }, + })); + + graph = addNode(graph, node('counter', 'evidence', { + epistemic: { + kind: 'fact', + confidence: 0.5, + verification: 'verified', + temporal: {}, + }, + })); + + graph = addNode(graph, node('thesis', 'thesis')); + + graph = addEdge(graph, { + id: 's', + source: 'support', + target: 'thesis', + type: 'supports', + strength: 1, + confidence: 1, + }); + + graph = addEdge(graph, { + id: 'c', + source: 'counter', + target: 'thesis', + type: 'contradicts', + strength: 1, + confidence: 1, + }); + + const balance = evidenceBalance(graph, 'thesis'); + + expect(balance.supportScore).toBeGreaterThan( + balance.contradictionScore, + ); + expect(findUnresolvedContradictions(graph)).toHaveLength(1); + }); + + test('detects open questions and knowledge gaps', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, node('q1', 'question')); + + const gaps = findKnowledgeGaps(graph); + expect(gaps.openQuestionIds).toContain('q1'); + }); + + test('finds cross-context analogies', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, node('a', 'experience', { + tags: ['liquidity-shock'], + context: { + marketRegimes: ['risk-off'], + horizons: ['short'], + }, + memory: { + system: 'episodic', + stage: 'raw_experience', + }, + })); + + graph = addNode(graph, node('b', 'experience', { + tags: ['liquidity-shock'], + context: { + marketRegimes: ['risk-off'], + horizons: ['short'], + }, + memory: { + system: 'episodic', + stage: 'raw_experience', + }, + })); + + expect(findAnalogies(graph, 'a')[0]?.node.id).toBe('b'); + }); + + test('groups repeated error patterns', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + for (const id of ['e1', 'e2']) { + graph = addNode(graph, node(id, 'error', { + errorClass: 'FORECAST_ERROR', + context: { + marketRegimes: ['risk-off'], + horizons: ['short'], + }, + })); + } + + expect(repeatedErrorPatterns(graph)).toHaveLength(1); + }); +}); diff --git a/tests/brain-retrieval.test.ts b/tests/brain-retrieval.test.ts new file mode 100644 index 00000000..69dfab7d --- /dev/null +++ b/tests/brain-retrieval.test.ts @@ -0,0 +1,235 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + inspectBrainGraph, +} from '@/lib/brain/brain-health'; + +import { + addEdge, + addNode, + createEmptyBrainGraph, +} from '@/lib/brain/graph-ops'; + +import { + decayedRetention, + transitionMemoryStage, +} from '@/lib/brain/memory-dynamics'; + +import { + buildWorkingMemoryFrame, + retrieveBrainGraph, + spreadActivation, +} from '@/lib/brain/retrieval'; + +function memoryNode( + id: string, + label: string, + summary: string, +) { + return { + id, + type: 'experience' as const, + label, + summary, + context: {}, + epistemic: { + kind: 'interpretation' as const, + confidence: 0.8, + verification: 'partially_verified' as const, + temporal: {}, + }, + memory: { + system: 'episodic' as const, + stage: 'raw_experience' as const, + salience: { + novelty: 0.5, + surprise: 0.5, + materiality: 0.8, + urgency: 0.2, + riskImpact: 0.5, + expectedUtility: 0.8, + }, + activation: 0, + retentionStrength: 1, + consolidationScore: 0, + accessCount: 0, + rehearsalCount: 0, + lastReinforcedAt: '2026-01-01T00:00:00.000Z', + decayHalfLifeHours: 24, + retentionLock: false, + pendingReview: false, + }, + audit: { + updatedAt: '2026-01-01T00:00:00.000Z', + }, + }; +} + +describe('Startup Brain retrieval and memory dynamics', () => { + test('retrieves relevant memory with explainable scoring', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode( + graph, + memoryNode( + 'rates', + 'Rates shock', + 'Higher rates compressed equity valuations.', + ), + ); + + graph = addNode( + graph, + memoryNode( + 'crypto', + 'Crypto liquidity', + 'Digital asset liquidity weakened.', + ), + ); + + const results = retrieveBrainGraph( + graph, + { + text: 'rates equity valuations', + limit: 10, + }, + { + now: '2026-01-01T01:00:00.000Z', + }, + ); + + expect(results[0]?.node.id).toBe('rates'); + expect(results[0]?.reasons).toContain('text_match'); + }); + + test('spreads activation through semantic connections', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, memoryNode('a', 'A', 'Alpha')); + graph = addNode(graph, memoryNode('b', 'B', 'Beta')); + + graph = addEdge(graph, { + id: 'ab', + source: 'a', + target: 'b', + type: 'related_to', + directed: false, + strength: 1, + confidence: 1, + }); + + const activation = spreadActivation(graph, ['a'], 2, 0.5); + + expect(activation.get('a')).toBe(1); + expect(activation.get('b')).toBe(0.5); + }); + + test('models memory decay without destructive deletion', () => { + const parsedGraph = addNode( + createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ), + memoryNode('memory', 'Memory', 'Test memory'), + ); + + const node = parsedGraph.nodes[0]!; + + expect( + decayedRetention( + node, + '2026-01-02T00:00:00.000Z', + ), + ).toBeCloseTo(0.5, 5); + }); + + test('enforces staged memory consolidation', () => { + const graph = addNode( + createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ), + memoryNode('memory', 'Memory', 'Test memory'), + ); + + const raw = graph.nodes[0]!; + + expect(() => + transitionMemoryStage(raw, 'validated_lesson'), + ).toThrow(); + + const interpreted = transitionMemoryStage( + raw, + 'interpreted_experience', + ); + + const candidate = transitionMemoryStage( + interpreted, + 'lesson_candidate', + ); + + const validated = transitionMemoryStage( + candidate, + 'validated_lesson', + ); + + expect(validated.memory?.stage).toBe('validated_lesson'); + }); + + test('builds bounded working memory from retrieval results', () => { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode(graph, memoryNode('a', 'A', 'rates')); + graph = addNode(graph, memoryNode('b', 'B', 'rates')); + + const results = retrieveBrainGraph( + graph, + { text: 'rates', limit: 10 }, + { now: '2026-01-01T01:00:00.000Z' }, + ); + + const frame = buildWorkingMemoryFrame(results, { + id: 'wm-1', + purpose: 'test', + capacity: 1, + createdAt: '2026-01-01T01:00:00.000Z', + }); + + expect(frame.focusNodeIds).toHaveLength(1); + }); + + test('produces a metacognitive health report', () => { + const graph = addNode( + createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ), + memoryNode( + 'orphan', + 'Orphan memory', + 'Unconnected operational memory.', + ), + ); + + const report = inspectBrainGraph( + graph, + '2026-01-01T01:00:00.000Z', + ); + + expect(report.orphanNodeIds).toContain('orphan'); + expect(report.operationalNodesWithoutContext).toContain('orphan'); + }); +}); From e0f6a5d727e7d02a2e24425bf608cd35c0d09db9 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 18:48:34 +0200 Subject: [PATCH 43/62] Add governed Startup Brain gateway --- lib/brain/gateway/budget.ts | 136 +++++++++ lib/brain/gateway/gateway.ts | 516 +++++++++++++++++++++++++++++++++++ lib/brain/gateway/index.ts | 6 + lib/brain/gateway/policy.ts | 240 ++++++++++++++++ lib/brain/gateway/routing.ts | 134 +++++++++ lib/brain/gateway/schema.ts | 186 +++++++++++++ lib/brain/gateway/store.ts | 89 ++++++ lib/brain/index.ts | 1 + tests/brain-gateway.test.ts | 381 ++++++++++++++++++++++++++ 9 files changed, 1689 insertions(+) create mode 100644 lib/brain/gateway/budget.ts create mode 100644 lib/brain/gateway/gateway.ts create mode 100644 lib/brain/gateway/index.ts create mode 100644 lib/brain/gateway/policy.ts create mode 100644 lib/brain/gateway/routing.ts create mode 100644 lib/brain/gateway/schema.ts create mode 100644 lib/brain/gateway/store.ts create mode 100644 tests/brain-gateway.test.ts diff --git a/lib/brain/gateway/budget.ts b/lib/brain/gateway/budget.ts new file mode 100644 index 00000000..5b2c3888 --- /dev/null +++ b/lib/brain/gateway/budget.ts @@ -0,0 +1,136 @@ +import type { + BrainGraphNode, +} from '@/lib/brain/graph-schema'; + +import type { + BrainRetrievalResult, +} from '@/lib/brain/retrieval'; + +import type { + BrainReadBudget, +} from '@/lib/brain/gateway/schema'; + +export type BrainNodeView = { + id: string; + type: BrainGraphNode['type']; + label: string; + summary: string; + content?: string; + rationaleSummary: string; + status: BrainGraphNode['status']; + tags: string[]; + keywords: string[]; + context: BrainGraphNode['context']; + epistemic?: BrainGraphNode['epistemic']; + memory?: BrainGraphNode['memory']; + metadata?: BrainGraphNode['metadata']; + version: number; +}; + +export type BudgetedRetrievalResult = Omit< + BrainRetrievalResult, + 'node' +> & { + node: BrainNodeView; +}; + +function clip( + value: string, + maxChars: number, +): string { + if (maxChars <= 0) { + return ''; + } + + if (value.length <= maxChars) { + return value; + } + + return `${value.slice(0, Math.max(0, maxChars - 1))}…`; +} + +export function projectNodeForRead( + node: BrainGraphNode, + budget: BrainReadBudget, + remainingTotalChars: number, +): { + view: BrainNodeView; + consumedChars: number; +} { + const allowedChars = Math.min( + budget.maxContentCharsPerNode, + Math.max(0, remainingTotalChars), + ); + + const content = budget.includeContent + ? clip(node.content, allowedChars) + : ''; + + const view: BrainNodeView = { + id: node.id, + type: node.type, + label: node.label, + summary: node.summary, + rationaleSummary: node.rationaleSummary, + status: node.status, + tags: node.tags, + keywords: node.keywords, + context: node.context, + epistemic: node.epistemic, + memory: node.memory, + version: node.version, + }; + + if (budget.includeContent) { + view.content = content; + } + + if (budget.includeMetadata) { + view.metadata = node.metadata; + } + + return { + view, + consumedChars: content.length, + }; +} + +export function applyReadBudget( + results: BrainRetrievalResult[], + budget: BrainReadBudget, +): { + results: BudgetedRetrievalResult[]; + truncated: boolean; + totalContentChars: number; +} { + const selected = results.slice(0, budget.maxResults); + + let remaining = budget.maxTotalContentChars; + let totalContentChars = 0; + + const budgeted: BudgetedRetrievalResult[] = []; + + for (const result of selected) { + const projected = projectNodeForRead( + result.node, + budget, + remaining, + ); + + remaining -= projected.consumedChars; + totalContentChars += projected.consumedChars; + + budgeted.push({ + ...result, + node: projected.view, + }); + } + + return { + results: budgeted, + truncated: + results.length > selected.length || + totalContentChars >= budget.maxTotalContentChars, + totalContentChars, + }; +} diff --git a/lib/brain/gateway/gateway.ts b/lib/brain/gateway/gateway.ts new file mode 100644 index 00000000..006ccc1a --- /dev/null +++ b/lib/brain/gateway/gateway.ts @@ -0,0 +1,516 @@ +import { + inspectBrainGraph, +} from '@/lib/brain/brain-health'; + +import { + kHopSubgraph, + neighbors, + requireNode, +} from '@/lib/brain/graph-ops'; + +import { + retrieveBrainGraph, +} from '@/lib/brain/retrieval'; + +import { + BrainGraphEventSchema, +} from '@/lib/brain/events'; + +import { + applyReadBudget, + projectNodeForRead, +} from '@/lib/brain/gateway/budget'; + +import { + canCommitMutation, + canInspectBrainHealth, + canInspectGraph, + canProposeMutation, + canReadNode, + canUseRetrieval, +} from '@/lib/brain/gateway/policy'; + +import { + routeBrainIntent, +} from '@/lib/brain/gateway/routing'; + +import { + BrainGatewayPrincipalSchema, + BrainGraphExploreRequestSchema, + BrainMutationCommitRequestSchema, + BrainMutationProposalSchema, + BrainNodeInspectRequestSchema, + BrainReadRequestSchema, + type BrainAuditRecord, + type BrainGraphExploreRequestInput, + type BrainMutationCommitRequestInput, + type BrainMutationProposalInput, + type BrainNodeInspectRequestInput, + type BrainReadRequestInput, +} from '@/lib/brain/gateway/schema'; + +import type { + BrainAuditStore, + BrainGraphStore, +} from '@/lib/brain/gateway/store'; + +function makeAuditId( + requestId: string, + suffix: string, +): string { + return `brain-audit:${requestId}:${suffix}`; +} + +export class BrainGateway { + constructor( + private readonly graphStore: BrainGraphStore, + private readonly auditStore: BrainAuditStore, + private readonly clock: () => string = () => + new Date().toISOString(), + ) {} + + private async audit( + record: Omit & { at?: string }, + ): Promise { + await this.auditStore.append({ + ...record, + at: record.at ?? this.clock(), + }); + } + + async read( + requestInput: BrainReadRequestInput, + ) { + const request = + BrainReadRequestSchema.parse(requestInput); + + const route = routeBrainIntent(request.intent); + + if (!route.brainRequired) { + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'external-route', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.read', + outcome: 'routed_external', + reason: route.explanation, + metadata: { + routes: route.routes, + intent: route.intent, + }, + }); + + return { + route, + results: [], + truncated: false, + totalContentChars: 0, + }; + } + + const permission = canUseRetrieval( + request.principal, + ); + + if (!permission.allowed) { + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.read', + outcome: 'denied', + reason: permission.reason, + metadata: { + intent: request.intent, + }, + }); + + throw new Error(permission.reason); + } + + const graph = + await this.graphStore.getSnapshot(); + + const retrieval = retrieveBrainGraph( + graph, + { + ...request.query, + maxHops: Math.min( + request.query.maxHops, + request.budget.maxHops, + ), + limit: Math.min( + request.query.limit, + request.budget.maxResults, + ), + nodeTypes: + request.requestedNodeTypes.length > 0 + ? request.requestedNodeTypes + : request.query.nodeTypes, + }, + { + now: request.query.asOf ?? this.clock(), + }, + ); + + const authorized = retrieval.filter( + (result) => + canReadNode( + request.principal, + result.node, + ).allowed, + ); + + const budgeted = applyReadBudget( + authorized, + request.budget, + ); + + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'allowed', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.read', + outcome: 'allowed', + reason: 'brain_retrieval_completed', + graphRevisionBefore: graph.revision, + graphRevisionAfter: graph.revision, + metadata: { + intent: request.intent, + returned: budgeted.results.length, + truncated: budgeted.truncated, + }, + }); + + return { + route, + ...budgeted, + }; + } + + async inspectNode( + requestInput: BrainNodeInspectRequestInput, + ) { + const request = + BrainNodeInspectRequestSchema.parse( + requestInput, + ); + + const permission = canInspectGraph( + request.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + const graph = + await this.graphStore.getSnapshot(); + + const node = requireNode( + graph, + request.nodeId, + ); + + const nodeRead = + canReadNode(request.principal, node); + + if (!nodeRead.allowed) { + throw new Error(nodeRead.reason); + } + + const projected = projectNodeForRead( + node, + request.budget, + request.budget.maxTotalContentChars, + ); + + const neighborViews = request.includeNeighbors + ? neighbors(graph, node.id) + .filter( + (candidate) => + canReadNode( + request.principal, + candidate, + ).allowed, + ) + .slice(0, request.neighborLimit) + .map((candidate) => + projectNodeForRead( + candidate, + request.budget, + request.budget.maxContentCharsPerNode, + ).view, + ) + : []; + + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'inspect', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.inspect_node', + outcome: 'allowed', + reason: 'node_inspection_completed', + graphRevisionBefore: graph.revision, + graphRevisionAfter: graph.revision, + metadata: { + nodeId: request.nodeId, + neighborCount: neighborViews.length, + }, + }); + + return { + node: projected.view, + neighbors: neighborViews, + }; + } + + async exploreGraph( + requestInput: BrainGraphExploreRequestInput, + ) { + const request = + BrainGraphExploreRequestSchema.parse( + requestInput, + ); + + const permission = canInspectGraph( + request.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + const graph = + await this.graphStore.getSnapshot(); + + const rawSubgraph = kHopSubgraph( + graph, + request.seedNodeIds, + request.maxHops, + ); + + const allowedNodeIds = new Set( + rawSubgraph.nodes + .filter( + (node) => + canReadNode( + request.principal, + node, + ).allowed, + ) + .slice(0, request.maxNodes) + .map((node) => node.id), + ); + + const subgraph = { + ...rawSubgraph, + nodes: rawSubgraph.nodes.filter( + (node) => allowedNodeIds.has(node.id), + ), + edges: rawSubgraph.edges.filter( + (edge) => + allowedNodeIds.has(edge.source) && + allowedNodeIds.has(edge.target), + ), + }; + + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'explore', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.explore_graph', + outcome: 'allowed', + reason: 'graph_exploration_completed', + graphRevisionBefore: graph.revision, + graphRevisionAfter: graph.revision, + metadata: { + nodeCount: subgraph.nodes.length, + edgeCount: subgraph.edges.length, + }, + }); + + return subgraph; + } + + async health(input: { + requestId: string; + principal: BrainReadRequestInput['principal']; +}) { + const principal = + BrainGatewayPrincipalSchema.parse( + input.principal, + ); + + const permission = + canInspectBrainHealth(principal); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + const graph = + await this.graphStore.getSnapshot(); + + const report = inspectBrainGraph( + graph, + this.clock(), + ); + + await this.audit({ + auditId: makeAuditId( + input.requestId, + 'health', + ), + requestId: input.requestId, + actor: principal.actor, + action: 'brain.health', + outcome: 'allowed', + reason: 'brain_health_inspection_completed', + graphRevisionBefore: graph.revision, + graphRevisionAfter: graph.revision, + metadata: { + nodeCount: report.stats.nodeCount, + edgeCount: report.stats.edgeCount, + }, + }); + + return report; +} + + async proposeMutation( + proposalInput: BrainMutationProposalInput, + ) { + const proposal = + BrainMutationProposalSchema.parse( + proposalInput, + ); + + const permission = canProposeMutation( + proposal.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + for (const event of proposal.events) { + BrainGraphEventSchema.parse(event); + } + + const graph = + await this.graphStore.getSnapshot(); + + await this.audit({ + auditId: makeAuditId( + proposal.requestId, + 'proposal', + ), + requestId: proposal.requestId, + actor: proposal.principal.actor, + action: 'brain.propose_mutation', + outcome: 'proposed', + reason: 'mutation_requires_control_plane_commit', + graphRevisionBefore: graph.revision, + graphRevisionAfter: graph.revision, + metadata: { + proposalId: proposal.proposalId, + eventCount: proposal.events.length, + }, + }); + + return { + proposal, + status: 'pending_control_plane' as const, + graphRevision: graph.revision, + }; + } + + async commitMutation( + requestInput: BrainMutationCommitRequestInput, + ) { + const request = + BrainMutationCommitRequestSchema.parse( + requestInput, + ); + + const graph = + await this.graphStore.getSnapshot(); + + const permission = canCommitMutation( + request.principal, + graph, + request.proposal.events, + request.approval, + ); + + if (!permission.allowed) { + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'commit-denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.commit_mutation', + outcome: 'denied', + reason: permission.reason, + graphRevisionBefore: graph.revision, + graphRevisionAfter: graph.revision, + metadata: { + proposalId: request.proposal.proposalId, + }, + }); + + throw new Error(permission.reason); + } + + const committed = + await this.graphStore.commitEvents({ + events: request.proposal.events, + expectedRevision: + request.expectedRevision, + }); + + await this.audit({ + auditId: makeAuditId( + request.requestId, + 'committed', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'brain.commit_mutation', + outcome: 'committed', + reason: 'mutation_committed', + graphRevisionBefore: graph.revision, + graphRevisionAfter: committed.revision, + metadata: { + proposalId: request.proposal.proposalId, + eventCount: + request.proposal.events.length, + }, + }); + + return { + graphRevisionBefore: graph.revision, + graphRevisionAfter: committed.revision, + committedEventCount: + request.proposal.events.length, + }; + } +} diff --git a/lib/brain/gateway/index.ts b/lib/brain/gateway/index.ts new file mode 100644 index 00000000..d3072a98 --- /dev/null +++ b/lib/brain/gateway/index.ts @@ -0,0 +1,6 @@ +export * from '@/lib/brain/gateway/schema'; +export * from '@/lib/brain/gateway/routing'; +export * from '@/lib/brain/gateway/policy'; +export * from '@/lib/brain/gateway/budget'; +export * from '@/lib/brain/gateway/store'; +export * from '@/lib/brain/gateway/gateway'; diff --git a/lib/brain/gateway/policy.ts b/lib/brain/gateway/policy.ts new file mode 100644 index 00000000..b8b05e83 --- /dev/null +++ b/lib/brain/gateway/policy.ts @@ -0,0 +1,240 @@ +import type { + BrainGraph, + BrainGraphEvent, + BrainGraphNode, +} from '@/lib/brain'; + +import { + type BrainCapability, + type BrainGatewayPrincipal, + type BrainMutationApproval, +} from '@/lib/brain/gateway/schema'; + +export type BrainAuthorizationDecision = { + allowed: boolean; + reason: string; +}; + +function hasCapability( + principal: BrainGatewayPrincipal, + capability: BrainCapability, +): boolean { + return ( + principal.capabilities.includes('brain.admin') || + principal.capabilities.includes(capability) + ); +} + +function explicitReadScopeAllows( + principal: BrainGatewayPrincipal, + node: BrainGraphNode, +): boolean { + const agentScope = node.governance.readableByAgentIds; + const departmentScope = node.governance.readableByDepartmentIds; + + if (agentScope.length === 0 && departmentScope.length === 0) { + return true; + } + + return ( + agentScope.includes(principal.actor.id) || + principal.departmentIds.some((departmentId) => + departmentScope.includes(departmentId), + ) + ); +} + +export function canReadNode( + principal: BrainGatewayPrincipal, + node: BrainGraphNode, +): BrainAuthorizationDecision { + if (!hasCapability(principal, 'brain.read')) { + return { + allowed: false, + reason: 'principal_missing_brain_read_capability', + }; + } + + if (!explicitReadScopeAllows(principal, node)) { + return { + allowed: false, + reason: 'node_read_scope_denied', + }; + } + + if ( + node.governance.visibility === 'confidential' && + !hasCapability(principal, 'brain.read_confidential') + ) { + return { + allowed: false, + reason: 'confidential_memory_requires_capability', + }; + } + + if ( + node.governance.visibility === 'restricted' && + !hasCapability(principal, 'brain.read_restricted') + ) { + return { + allowed: false, + reason: 'restricted_memory_requires_capability', + }; + } + + return { + allowed: true, + reason: 'read_allowed', + }; +} + +export function canUseRetrieval( + principal: BrainGatewayPrincipal, +): BrainAuthorizationDecision { + return hasCapability(principal, 'brain.retrieve') + ? { allowed: true, reason: 'retrieval_allowed' } + : { allowed: false, reason: 'principal_missing_brain_retrieve_capability' }; +} + +export function canInspectGraph( + principal: BrainGatewayPrincipal, +): BrainAuthorizationDecision { + return hasCapability(principal, 'brain.inspect') + ? { allowed: true, reason: 'inspection_allowed' } + : { allowed: false, reason: 'principal_missing_brain_inspect_capability' }; +} + +export function canInspectBrainHealth( + principal: BrainGatewayPrincipal, +): BrainAuthorizationDecision { + return hasCapability(principal, 'brain.health') + ? { allowed: true, reason: 'health_inspection_allowed' } + : { allowed: false, reason: 'principal_missing_brain_health_capability' }; +} + +export function canProposeMutation( + principal: BrainGatewayPrincipal, +): BrainAuthorizationDecision { + return hasCapability(principal, 'brain.propose_write') + ? { allowed: true, reason: 'mutation_proposal_allowed' } + : { allowed: false, reason: 'principal_missing_brain_propose_write_capability' }; +} + +function targetNodesForEvent( + graph: BrainGraph, + event: BrainGraphEvent, +): BrainGraphNode[] { + const ids = new Set(); + + switch (event.type) { + case 'node_added': + return []; + + case 'node_updated': + case 'node_removed': + case 'memory_accessed': + case 'memory_reinforced': + case 'memory_stage_changed': + ids.add(event.payload.nodeId); + break; + + case 'edge_added': + ids.add(event.payload.edge.source); + ids.add(event.payload.edge.target); + break; + + case 'edge_removed': { + const edge = graph.edges.find((candidate) => candidate.id === event.payload.edgeId); + if (edge) { + ids.add(edge.source); + ids.add(edge.target); + } + break; + } + + case 'node_superseded': + ids.add(event.payload.nodeId); + ids.add(event.payload.byNodeId); + break; + } + + return graph.nodes.filter((node) => ids.has(node.id)); +} + +function writeScopeAllows( + principal: BrainGatewayPrincipal, + node: BrainGraphNode, +): boolean { + const agentScope = node.governance.writableByAgentIds; + const departmentScope = node.governance.writableByDepartmentIds; + + if (agentScope.length === 0 && departmentScope.length === 0) { + return true; + } + + return ( + agentScope.includes(principal.actor.id) || + principal.departmentIds.some((departmentId) => + departmentScope.includes(departmentId), + ) + ); +} + +export function canCommitMutation( + principal: BrainGatewayPrincipal, + graph: BrainGraph, + events: BrainGraphEvent[], + approval?: BrainMutationApproval, +): BrainAuthorizationDecision { + if (!hasCapability(principal, 'brain.commit_write')) { + return { + allowed: false, + reason: 'principal_missing_brain_commit_write_capability', + }; + } + + if (principal.actor.kind === 'agent') { + return { + allowed: false, + reason: 'agents_may_propose_but_never_commit_brain_mutations', + }; + } + + for (const event of events) { + const targets = targetNodesForEvent(graph, event); + + for (const node of targets) { + if ( + node.governance.immutable && + event.type !== 'memory_accessed' && + event.type !== 'memory_reinforced' + ) { + return { + allowed: false, + reason: `immutable_node_mutation_denied:${node.id}`, + }; + } + + if (!writeScopeAllows(principal, node)) { + return { + allowed: false, + reason: `node_write_scope_denied:${node.id}`, + }; + } + + if (node.governance.humanApprovalRequired) { + if (!approval || approval.approvedBy.kind !== 'human') { + return { + allowed: false, + reason: `human_approval_required:${node.id}`, + }; + } + } + } + } + + return { + allowed: true, + reason: 'mutation_commit_allowed', + }; +} diff --git a/lib/brain/gateway/routing.ts b/lib/brain/gateway/routing.ts new file mode 100644 index 00000000..19afc7ff --- /dev/null +++ b/lib/brain/gateway/routing.ts @@ -0,0 +1,134 @@ +import { + BrainRouteDecisionSchema, + type BrainInformationIntent, + type BrainRouteDecision, +} from '@/lib/brain/gateway/schema'; + +const ROUTES: Record = { + institutional_memory: { + intent: 'institutional_memory', + routes: ['brain'], + brainRequired: true, + explanation: 'Institutional memory belongs to Startup Brain.', + }, + + prior_reasoning: { + intent: 'prior_reasoning', + routes: ['brain'], + brainRequired: true, + explanation: 'Prior company reasoning must be retrieved from Startup Brain.', + }, + + prior_decisions: { + intent: 'prior_decisions', + routes: ['brain'], + brainRequired: true, + explanation: 'Prior decisions are institutional records.', + }, + + past_experiences: { + intent: 'past_experiences', + routes: ['brain'], + brainRequired: true, + explanation: 'Past company experiences belong to institutional memory.', + }, + + validated_lessons: { + intent: 'validated_lessons', + routes: ['brain'], + brainRequired: true, + explanation: 'Validated lessons are consolidated Startup Brain memory.', + }, + + policies_and_sops: { + intent: 'policies_and_sops', + routes: ['brain', 'control_plane'], + brainRequired: true, + explanation: + 'Startup Brain provides institutional knowledge; Control Plane remains authoritative for executable policy.', + }, + + graph_exploration: { + intent: 'graph_exploration', + routes: ['brain'], + brainRequired: true, + explanation: 'Knowledge-graph exploration is a Startup Brain function.', + }, + + brain_health: { + intent: 'brain_health', + routes: ['brain'], + brainRequired: true, + explanation: 'Brain-health inspection operates on the institutional graph.', + }, + + current_market_price: { + intent: 'current_market_price', + routes: ['market_data'], + brainRequired: false, + explanation: + 'Current prices must come from an external market-data provider, not institutional memory.', + }, + + historical_market_data: { + intent: 'historical_market_data', + routes: ['market_data'], + brainRequired: false, + explanation: + 'Raw historical price series belong in market-data infrastructure, not Startup Brain.', + }, + + latest_company_filing: { + intent: 'latest_company_filing', + routes: ['filings'], + brainRequired: false, + explanation: + 'Latest filings must be fetched from an authoritative external source.', + }, + + latest_news: { + intent: 'latest_news', + routes: ['web'], + brainRequired: false, + explanation: + 'Latest news is current external information and must be fetched externally.', + }, + + web_research: { + intent: 'web_research', + routes: ['web'], + brainRequired: false, + explanation: + 'Open-web research is external evidence and is not replaced by Startup Brain.', + }, + + live_portfolio_state: { + intent: 'live_portfolio_state', + routes: ['portfolio'], + brainRequired: false, + explanation: + 'Live portfolio state must come from the operational portfolio data source.', + }, + + execution_request: { + intent: 'execution_request', + routes: ['control_plane'], + brainRequired: false, + explanation: + 'Execution authority belongs to the governed Control Plane and human CEO, never Startup Brain.', + }, + + mixed_brain_and_current_context: { + intent: 'mixed_brain_and_current_context', + routes: ['brain', 'market_data', 'filings', 'web', 'portfolio'], + brainRequired: true, + explanation: + 'The task needs institutional memory combined with current external context.', + }, +}; + +export function routeBrainIntent( + intent: BrainInformationIntent, +): BrainRouteDecision { + return BrainRouteDecisionSchema.parse(ROUTES[intent]); +} diff --git a/lib/brain/gateway/schema.ts b/lib/brain/gateway/schema.ts new file mode 100644 index 00000000..ae47543d --- /dev/null +++ b/lib/brain/gateway/schema.ts @@ -0,0 +1,186 @@ +import { z } from 'zod'; + +import { + BrainActorSchema, + ContextEnvelopeSchema, + TimestampSchema, +} from '@/lib/brain/core-schema'; + +import { + BrainGraphEventSchema, +} from '@/lib/brain/events'; + +import { + BrainGraphNodeTypeSchema, +} from '@/lib/brain/graph-schema'; + +import { + BrainRetrievalQuerySchema, +} from '@/lib/brain/retrieval'; + +/** + * Capabilities are granted by trusted company infrastructure. + * Agents must never self-assert these values. + */ +export const BrainCapabilitySchema = z.enum([ + 'brain.read', + 'brain.retrieve', + 'brain.inspect', + 'brain.health', + 'brain.propose_write', + 'brain.commit_write', + 'brain.read_confidential', + 'brain.read_restricted', + 'brain.admin', +]); + +export const BrainGatewayPrincipalSchema = z.object({ + actor: BrainActorSchema, + departmentIds: z.array(z.string().min(1)).default([]), + capabilities: z.array(BrainCapabilitySchema).default([]), + sessionId: z.string().min(1).optional(), + issuedBy: z.string().min(1).default('control-plane'), +}); + +export const BrainInformationIntentSchema = z.enum([ + 'institutional_memory', + 'prior_reasoning', + 'prior_decisions', + 'past_experiences', + 'validated_lessons', + 'policies_and_sops', + 'graph_exploration', + 'brain_health', + + 'current_market_price', + 'historical_market_data', + 'latest_company_filing', + 'latest_news', + 'web_research', + 'live_portfolio_state', + 'execution_request', + + 'mixed_brain_and_current_context', +]); + +export const BrainRouteSchema = z.enum([ + 'brain', + 'market_data', + 'filings', + 'web', + 'portfolio', + 'control_plane', +]); + +export const BrainRouteDecisionSchema = z.object({ + intent: BrainInformationIntentSchema, + routes: z.array(BrainRouteSchema).min(1), + brainRequired: z.boolean(), + explanation: z.string().min(1), +}); + +export const BrainReadBudgetSchema = z.object({ + maxResults: z.number().int().positive().max(200).default(20), + maxHops: z.number().int().min(0).max(12).default(3), + maxContentCharsPerNode: z.number().int().min(0).max(100_000).default(4_000), + maxTotalContentChars: z.number().int().min(0).max(1_000_000).default(40_000), + includeContent: z.boolean().default(true), + includeMetadata: z.boolean().default(true), +}); + +export const BrainReadRequestSchema = z.object({ + requestId: z.string().min(1), + principal: BrainGatewayPrincipalSchema, + intent: BrainInformationIntentSchema, + purpose: z.string().min(1), + query: BrainRetrievalQuerySchema, + context: ContextEnvelopeSchema, + budget: BrainReadBudgetSchema, + requestedNodeTypes: z.array(BrainGraphNodeTypeSchema).default([]), +}); + +export const BrainNodeInspectRequestSchema = z.object({ + requestId: z.string().min(1), + principal: BrainGatewayPrincipalSchema, + intent: BrainInformationIntentSchema.default('graph_exploration'), + purpose: z.string().min(1), + nodeId: z.string().min(1), + includeNeighbors: z.boolean().default(true), + neighborLimit: z.number().int().positive().max(200).default(50), + budget: BrainReadBudgetSchema, +}); + +export const BrainGraphExploreRequestSchema = z.object({ + requestId: z.string().min(1), + principal: BrainGatewayPrincipalSchema, + purpose: z.string().min(1), + seedNodeIds: z.array(z.string().min(1)).min(1), + maxHops: z.number().int().min(0).max(12).default(2), + maxNodes: z.number().int().positive().max(1_000).default(200), +}); + +export const BrainMutationProposalSchema = z.object({ + proposalId: z.string().min(1), + requestId: z.string().min(1), + principal: BrainGatewayPrincipalSchema, + purpose: z.string().min(1), + reason: z.string().min(1), + events: z.array(BrainGraphEventSchema).min(1).max(100), + proposedAt: TimestampSchema, + context: ContextEnvelopeSchema, +}); + +export const BrainMutationApprovalSchema = z.object({ + approvedBy: BrainActorSchema, + approvedAt: TimestampSchema, + reason: z.string().min(1), +}); + +export type BrainMutationApproval = z.infer< + typeof BrainMutationApprovalSchema +>; + +export const BrainMutationCommitRequestSchema = z.object({ + requestId: z.string().min(1), + principal: BrainGatewayPrincipalSchema, + proposal: BrainMutationProposalSchema, + approval: BrainMutationApprovalSchema.optional(), + expectedRevision: z.number().int().min(0).optional(), +}); + +export const BrainAuditOutcomeSchema = z.enum([ + 'allowed', + 'denied', + 'routed_external', + 'proposed', + 'committed', + 'failed', +]); + +export const BrainAuditRecordSchema = z.object({ + auditId: z.string().min(1), + requestId: z.string().min(1), + at: TimestampSchema, + actor: BrainActorSchema, + action: z.string().min(1), + outcome: BrainAuditOutcomeSchema, + reason: z.string().default(''), + graphRevisionBefore: z.number().int().min(0).optional(), + graphRevisionAfter: z.number().int().min(0).optional(), + metadata: z.record(z.unknown()).default({}), +}); + +export type BrainCapability = z.infer; +export type BrainGatewayPrincipal = z.infer; +export type BrainInformationIntent = z.infer; +export type BrainRoute = z.infer; +export type BrainRouteDecision = z.infer; +export type BrainReadBudget = z.infer; +export type BrainReadRequestInput = z.input; +export type BrainReadRequest = z.infer; +export type BrainNodeInspectRequestInput = z.input; +export type BrainGraphExploreRequestInput = z.input; +export type BrainMutationProposalInput = z.input; +export type BrainMutationProposal = z.infer; +export type BrainMutationCommitRequestInput = z.input; +export type BrainAuditRecord = z.infer; diff --git a/lib/brain/gateway/store.ts b/lib/brain/gateway/store.ts new file mode 100644 index 00000000..c677c2f6 --- /dev/null +++ b/lib/brain/gateway/store.ts @@ -0,0 +1,89 @@ +import type { + BrainGraph, +} from '@/lib/brain/graph-schema'; + +import type { + BrainGraphEvent, + BrainGraphEventInput, +} from '@/lib/brain/events'; + +import { + applyBrainGraphEvent, +} from '@/lib/brain/events'; + +import { + BrainGraphSchema, +} from '@/lib/brain/graph-schema'; + +import { + BrainAuditRecordSchema, + type BrainAuditRecord, +} from '@/lib/brain/gateway/schema'; + +export interface BrainGraphStore { + getSnapshot(): Promise; + + commitEvents(input: { + events: BrainGraphEventInput[]; + expectedRevision?: number; + }): Promise; +} + +export interface BrainAuditStore { + append(record: BrainAuditRecord): Promise; + list(): Promise; +} + +export class InMemoryBrainGraphStore + implements BrainGraphStore +{ + private graph: BrainGraph; + + constructor(initialGraph: BrainGraph) { + this.graph = BrainGraphSchema.parse(initialGraph); + } + + async getSnapshot(): Promise { + return structuredClone(this.graph); + } + + async commitEvents(input: { + events: BrainGraphEventInput[]; + expectedRevision?: number; + }): Promise { + if ( + input.expectedRevision !== undefined && + input.expectedRevision !== this.graph.revision + ) { + throw new Error( + `brain_revision_conflict:expected=${input.expectedRevision}:actual=${this.graph.revision}`, + ); + } + + let next = this.graph; + + for (const event of input.events) { + next = applyBrainGraphEvent(next, event); + } + + this.graph = BrainGraphSchema.parse(next); + + return structuredClone(this.graph); + } +} + +export class InMemoryBrainAuditStore + implements BrainAuditStore +{ + private readonly records: BrainAuditRecord[] = []; + + async append(record: BrainAuditRecord): Promise { + this.records.push( + BrainAuditRecordSchema.parse(record), + ); + } + + async list(): Promise { + return structuredClone(this.records); + } +} diff --git a/lib/brain/index.ts b/lib/brain/index.ts index ad44d442..feb1fc94 100644 --- a/lib/brain/index.ts +++ b/lib/brain/index.ts @@ -9,3 +9,4 @@ export * from '@/lib/brain/reasoning'; export * from '@/lib/brain/learning'; export * from '@/lib/brain/events'; export * from '@/lib/brain/graph-foundation'; +export * from '@/lib/brain/gateway'; \ No newline at end of file diff --git a/tests/brain-gateway.test.ts b/tests/brain-gateway.test.ts new file mode 100644 index 00000000..a32d7c41 --- /dev/null +++ b/tests/brain-gateway.test.ts @@ -0,0 +1,381 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + BrainGateway, +} from '@/lib/brain/gateway/gateway'; + +import { + InMemoryBrainAuditStore, + InMemoryBrainGraphStore, +} from '@/lib/brain/gateway/store'; + +import { + routeBrainIntent, +} from '@/lib/brain/gateway/routing'; + +import { + addNode, + createEmptyBrainGraph, +} from '@/lib/brain/graph-ops'; + +function principal( + kind: 'agent' | 'human' | 'control_plane' | 'system', + id: string, + capabilities: Array< + | 'brain.read' + | 'brain.retrieve' + | 'brain.inspect' + | 'brain.health' + | 'brain.propose_write' + | 'brain.commit_write' + | 'brain.read_confidential' + | 'brain.read_restricted' + | 'brain.admin' + >, +) { + return { + actor: { kind, id }, + departmentIds: ['dept-research'], + capabilities, + issuedBy: 'control-plane', + }; +} + +function experienceNode(id: string) { + return { + id, + type: 'experience' as const, + label: 'Rates valuation experience', + summary: 'Higher rates compressed equity valuations.', + content: + 'Long-form institutional memory content that may be budget-truncated.', + rationaleSummary: 'Valuation sensitivity increased as rates moved higher.', + status: 'active' as const, + tags: ['rates', 'equities'], + keywords: ['valuation'], + context: { + departmentIds: ['dept-research'], + assetIds: ['asset:example'], + }, + epistemic: { + kind: 'interpretation' as const, + confidence: 0.8, + verification: 'partially_verified' as const, + uncertaintyReasons: [], + provenance: [], + evidenceForNodeIds: [], + evidenceAgainstNodeIds: [], + temporal: {}, + }, + memory: { + system: 'episodic' as const, + stage: 'interpreted_experience' as const, + salience: { + novelty: 0.3, + surprise: 0.3, + materiality: 0.8, + urgency: 0.2, + riskImpact: 0.6, + expectedUtility: 0.8, + }, + activation: 0, + retentionStrength: 1, + consolidationScore: 0.2, + accessCount: 0, + rehearsalCount: 0, + retentionLock: false, + pendingReview: false, + }, + governance: {}, + audit: { + createdAt: '2026-01-01T00:00:00.000Z', + updatedAt: '2026-01-01T00:00:00.000Z', + }, + version: 1, + metadata: {}, + }; +} + +async function gatewayWithNode() { + let graph = createEmptyBrainGraph( + 'test', + '2026-01-01T00:00:00.000Z', + ); + + graph = addNode( + graph, + experienceNode('exp:rates'), + '2026-01-01T00:00:01.000Z', + ); + + const graphStore = + new InMemoryBrainGraphStore(graph); + + const auditStore = + new InMemoryBrainAuditStore(); + + const gateway = new BrainGateway( + graphStore, + auditStore, + () => '2026-01-01T01:00:00.000Z', + ); + + return { + gateway, + graphStore, + auditStore, + }; +} + +describe('Brain Gateway', () => { + test('routes current market price away from Startup Brain', () => { + expect( + routeBrainIntent('current_market_price'), + ).toMatchObject({ + routes: ['market_data'], + brainRequired: false, + }); + }); + + test('routes mixed context to Brain plus current sources', () => { + const decision = routeBrainIntent( + 'mixed_brain_and_current_context', + ); + + expect(decision.brainRequired).toBe(true); + expect(decision.routes).toContain('brain'); + expect(decision.routes).toContain('market_data'); + expect(decision.routes).toContain('web'); + }); + + test('retrieves memory through capability and budget controls', async () => { + const { gateway } = + await gatewayWithNode(); + + const result = await gateway.read({ + requestId: 'read-1', + principal: principal( + 'agent', + 'lauti', + ['brain.read', 'brain.retrieve'], + ), + intent: 'institutional_memory', + purpose: 'Recall relevant valuation experience.', + query: { + text: 'rates valuation', + limit: 20, + }, + context: {}, + budget: { + maxResults: 5, + maxHops: 2, + maxContentCharsPerNode: 10, + maxTotalContentChars: 10, + includeContent: true, + includeMetadata: false, + }, + }); + + expect(result.results).toHaveLength(1); + expect(result.results[0]?.node.id).toBe( + 'exp:rates', + ); + expect( + result.results[0]?.node.content?.length, + ).toBeLessThanOrEqual(10); + }); + + test('denies retrieval without retrieve capability', async () => { + const { gateway } = + await gatewayWithNode(); + + await expect( + gateway.read({ + requestId: 'read-denied', + principal: principal( + 'agent', + 'lauti', + ['brain.read'], + ), + intent: 'institutional_memory', + purpose: 'Recall memory.', + query: { + text: 'rates', + }, + context: {}, + budget: {}, + }), + ).rejects.toThrow( + 'principal_missing_brain_retrieve_capability', + ); + }); + + test('agents may propose but never commit mutations', async () => { + const { gateway } = + await gatewayWithNode(); + + const agent = principal( + 'agent', + 'lauti', + [ + 'brain.read', + 'brain.retrieve', + 'brain.propose_write', + 'brain.commit_write', + ], + ); + + const proposal = { + proposalId: 'proposal-1', + requestId: 'mutation-1', + principal: agent, + purpose: 'Record a new interpreted experience.', + reason: 'Material learning from completed analysis.', + proposedAt: + '2026-01-01T01:00:00.000Z', + context: {}, + events: [ + { + eventId: 'event-1', + at: + '2026-01-01T01:00:00.000Z', + actor: agent.actor, + reason: 'Record experience', + type: 'node_added' as const, + payload: { + node: experienceNode('exp:new'), + }, + }, + ], + }; + + const proposed = + await gateway.proposeMutation( + proposal, + ); + + expect(proposed.status).toBe( + 'pending_control_plane', + ); + + await expect( + gateway.commitMutation({ + requestId: 'commit-agent', + principal: agent, + proposal, + }), + ).rejects.toThrow( + 'agents_may_propose_but_never_commit_brain_mutations', + ); + }); + + test('control plane can commit an authorized proposal with optimistic concurrency', async () => { + const { + gateway, + graphStore, + } = await gatewayWithNode(); + + const agent = principal( + 'agent', + 'lauti', + ['brain.propose_write'], + ); + + const proposal = { + proposalId: 'proposal-2', + requestId: 'mutation-2', + principal: agent, + purpose: 'Record a new interpreted experience.', + reason: 'Material learning.', + proposedAt: + '2026-01-01T01:00:00.000Z', + context: {}, + events: [ + { + eventId: 'event-2', + at: + '2026-01-01T01:00:00.000Z', + actor: agent.actor, + reason: 'Record experience', + type: 'node_added' as const, + payload: { + node: experienceNode('exp:new'), + }, + }, + ], + }; + + const before = + await graphStore.getSnapshot(); + + const controlPlane = principal( + 'control_plane', + 'company-control-plane', + ['brain.commit_write'], + ); + + const result = + await gateway.commitMutation({ + requestId: 'commit-control-plane', + principal: controlPlane, + proposal, + expectedRevision: before.revision, + }); + + expect( + result.committedEventCount, + ).toBe(1); + + expect( + result.graphRevisionAfter, + ).toBeGreaterThan( + result.graphRevisionBefore, + ); + + const after = + await graphStore.getSnapshot(); + + expect( + after.nodes.some( + (node) => node.id === 'exp:new', + ), + ).toBe(true); + }); + + test('every gateway action creates auditable records', async () => { + const { + gateway, + auditStore, + } = await gatewayWithNode(); + + await gateway.read({ + requestId: 'audit-read', + principal: principal( + 'agent', + 'lauti', + ['brain.read', 'brain.retrieve'], + ), + intent: 'institutional_memory', + purpose: 'Recall experience.', + query: { + text: 'rates', + }, + context: {}, + budget: {}, + }); + + const records = + await auditStore.list(); + + expect(records).toHaveLength(1); + expect(records[0]).toMatchObject({ + requestId: 'audit-read', + action: 'brain.read', + outcome: 'allowed', + }); + }); +}); From d6cd770cdeefa715450efdf584e340bf2ef2cb22 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 18:57:51 +0200 Subject: [PATCH 44/62] Add deterministic company control plane --- lib/control-plane/brain-bridge.ts | 49 ++ lib/control-plane/engine.ts | 834 ++++++++++++++++++++++ lib/control-plane/gates.ts | 356 +++++++++ lib/control-plane/index.ts | 9 + lib/control-plane/jobs.ts | 111 +++ lib/control-plane/permissions.ts | 263 +++++++ lib/control-plane/schema.ts | 279 ++++++++ lib/control-plane/spec.ts | 212 ++++++ lib/control-plane/state-machine.ts | 47 ++ lib/control-plane/store.ts | 155 ++++ tests/control-plane-engine.test.ts | 504 +++++++++++++ tests/control-plane-jobs.test.ts | 83 +++ tests/control-plane-state-machine.test.ts | 64 ++ 13 files changed, 2966 insertions(+) create mode 100644 lib/control-plane/brain-bridge.ts create mode 100644 lib/control-plane/engine.ts create mode 100644 lib/control-plane/gates.ts create mode 100644 lib/control-plane/index.ts create mode 100644 lib/control-plane/jobs.ts create mode 100644 lib/control-plane/permissions.ts create mode 100644 lib/control-plane/schema.ts create mode 100644 lib/control-plane/spec.ts create mode 100644 lib/control-plane/state-machine.ts create mode 100644 lib/control-plane/store.ts create mode 100644 tests/control-plane-engine.test.ts create mode 100644 tests/control-plane-jobs.test.ts create mode 100644 tests/control-plane-state-machine.test.ts diff --git a/lib/control-plane/brain-bridge.ts b/lib/control-plane/brain-bridge.ts new file mode 100644 index 00000000..4fc86696 --- /dev/null +++ b/lib/control-plane/brain-bridge.ts @@ -0,0 +1,49 @@ +import type { + BrainMutationApproval, + BrainMutationProposal, +} from '@/lib/brain/gateway/schema'; + +import { + BrainGateway, +} from '@/lib/brain/gateway/gateway'; + +/** + * Internal adapter used by the Company Control Plane after it has + * already authorized a permanent Startup Brain mutation. + * + * Agents never receive this principal and never call this bridge + * directly. + */ +export class ControlPlaneBrainBridge { + constructor( + private readonly brainGateway: BrainGateway, + private readonly controlPlaneId = + 'company-control-plane', + ) {} + + async commitAuthorizedProposal(input: { + requestId: string; + proposal: BrainMutationProposal; + approval?: BrainMutationApproval; + expectedRevision?: number; + }) { + return this.brainGateway.commitMutation({ + requestId: input.requestId, + principal: { + actor: { + kind: 'control_plane', + id: this.controlPlaneId, + }, + capabilities: [ + 'brain.commit_write', + ], + departmentIds: [], + issuedBy: this.controlPlaneId, + }, + proposal: input.proposal, + approval: input.approval, + expectedRevision: + input.expectedRevision, + }); + } +} diff --git a/lib/control-plane/engine.ts b/lib/control-plane/engine.ts new file mode 100644 index 00000000..4f83af10 --- /dev/null +++ b/lib/control-plane/engine.ts @@ -0,0 +1,834 @@ +import { + CreateWorkflowRequestSchema, + FinancialActionRequestSchema, + InvestmentWorkflowSchema, + RecordInvalidationRequestSchema, + RegisterArtifactRequestSchema, + ResolveInvalidationRequestSchema, + TransitionRequestSchema, + type AuthorizationDecision, + type ControlPlaneAuditRecord, + type ControlPlanePrincipal, + type InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +import { + canAuthorizeFinancialAction, + canCreateInvestmentWorkflow, + canRecordMaterialInvalidation, + canRegisterArtifact, + canRequestTransition, + canResolveMaterialInvalidation, +} from '@/lib/control-plane/permissions'; + +import { + assertStateTransitionShape, +} from '@/lib/control-plane/state-machine'; + +import { + evaluateWorkflowGates, +} from '@/lib/control-plane/gates'; + +import type { + ControlPlaneStore, +} from '@/lib/control-plane/store'; + +import { + IMMUTABLE_HISTORICAL_ARTIFACTS, +} from '@/lib/control-plane/spec'; + +function combineDecisions( + ...decisions: AuthorizationDecision[] +): AuthorizationDecision { + const missingRequirements = + decisions.flatMap( + (decision) => + decision.missingRequirements, + ); + + const denied = decisions.find( + (decision) => !decision.allowed, + ); + + return denied + ? { + allowed: false, + reason: denied.reason, + missingRequirements, + } + : { + allowed: true, + reason: 'all_control_plane_checks_passed', + missingRequirements: [], + }; +} + +export class CompanyControlPlane { + constructor( + private readonly store: ControlPlaneStore, + private readonly clock: () => string = () => + new Date().toISOString(), + ) {} + + private auditId( + requestId: string, + suffix: string, + ): string { + return `cp-audit:${requestId}:${suffix}`; + } + + private async audit( + record: Omit< + ControlPlaneAuditRecord, + 'at' + > & { + at?: string; + }, + ): Promise { + await this.store.appendAudit({ + ...record, + at: record.at ?? this.clock(), + }); + } + + private async duplicateResult( + requestId: string, + workflowId: string, + actor: ControlPlanePrincipal['actor'], + ) { + const workflow = + await this.requireWorkflow(workflowId); + + await this.audit({ + auditId: this.auditId( + requestId, + 'duplicate', + ), + requestId, + actor, + action: 'control_plane.request', + outcome: 'duplicate', + reason: + 'duplicate_request_ignored_idempotently', + workflowId, + workflowRevisionBefore: + workflow.revision, + workflowRevisionAfter: + workflow.revision, + metadata: {}, + }); + + return { + workflow, + duplicate: true as const, + }; + } + + private async requireWorkflow( + workflowId: string, + ): Promise { + const workflow = + await this.store.getWorkflow( + workflowId, + ); + + if (!workflow) { + throw new Error( + `workflow_not_found:${workflowId}`, + ); + } + + return workflow; + } + + private assertExpectedRevision( + workflow: InvestmentWorkflow, + expectedRevision?: number, + ): void { + if ( + expectedRevision !== undefined && + workflow.revision !== + expectedRevision + ) { + throw new Error( + `workflow_revision_conflict:expected=${expectedRevision}:actual=${workflow.revision}`, + ); + } + } + + async createWorkflow( + input: Parameters< + typeof CreateWorkflowRequestSchema.parse + >[0], + ) { + const request = + CreateWorkflowRequestSchema.parse(input); + + if ( + await this.store.hasProcessedRequest( + request.requestId, + ) + ) { + return this.duplicateResult( + request.requestId, + request.workflowId, + request.principal.actor, + ); + } + + const permission = + canCreateInvestmentWorkflow( + request.principal, + request.responsibleResearchAgentId, + ); + + if (!permission.allowed) { + await this.audit({ + auditId: this.auditId( + request.requestId, + 'denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.create', + outcome: 'denied', + reason: permission.reason, + workflowId: request.workflowId, + metadata: {}, + }); + + throw new Error(permission.reason); + } + + const now = this.clock(); + + const workflow = + InvestmentWorkflowSchema.parse({ + id: request.workflowId, + state: 'DRAFT', + revision: 0, + createdBy: + request.principal.actor, + createdAt: now, + updatedAt: now, + responsibleResearchAgentId: + request.responsibleResearchAgentId, + assetRef: request.assetRef, + artifacts: [], + invalidations: [], + metadata: request.metadata, + }); + + await this.store.createWorkflow( + workflow, + ); + + await this.store.markProcessedRequest( + request.requestId, + ); + + await this.audit({ + auditId: this.auditId( + request.requestId, + 'created', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.create', + outcome: 'created', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionAfter: + workflow.revision, + metadata: { + state: workflow.state, + }, + }); + + return { + workflow, + duplicate: false as const, + }; + } + + async registerArtifact( + input: Parameters< + typeof RegisterArtifactRequestSchema.parse + >[0], + ) { + const request = + RegisterArtifactRequestSchema.parse( + input, + ); + + if ( + await this.store.hasProcessedRequest( + request.requestId, + ) + ) { + return this.duplicateResult( + request.requestId, + request.workflowId, + request.principal.actor, + ); + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + if ( + request.artifact.workflowId !== + workflow.id + ) { + throw new Error( + 'artifact_workflow_id_mismatch', + ); + } + + if ( + request.artifact.createdBy.id !== + request.principal.actor.id || + request.artifact.createdBy.kind !== + request.principal.actor.kind + ) { + throw new Error( + 'artifact_creator_must_match_request_principal', + ); + } + + const permission = + canRegisterArtifact( + request.principal, + request.artifact.kind, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + if ( + workflow.artifacts.some( + (artifact) => + artifact.id === + request.artifact.id, + ) + ) { + throw new Error( + `artifact_id_already_exists:${request.artifact.id}`, + ); + } + + const now = this.clock(); + + workflow = { + ...workflow, + revision: workflow.revision + 1, + updatedAt: now, + artifacts: [ + ...workflow.artifacts, + request.artifact, + ], + }; + + workflow = + InvestmentWorkflowSchema.parse( + workflow, + ); + + const saved = + await this.store.replaceWorkflow({ + workflow, + expectedRevision: + workflow.revision - 1, + }); + + await this.store.markProcessedRequest( + request.requestId, + ); + + await this.audit({ + auditId: this.auditId( + request.requestId, + 'artifact', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.register_artifact', + outcome: 'recorded', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: + workflow.revision - 1, + workflowRevisionAfter: + workflow.revision, + metadata: { + artifactId: + request.artifact.id, + artifactKind: + request.artifact.kind, + immutableHistoricalRecord: + IMMUTABLE_HISTORICAL_ARTIFACTS.has( + request.artifact.kind, + ), + }, + }); + + return { + workflow: saved, + duplicate: false as const, + }; + } + + async transition( + input: Parameters< + typeof TransitionRequestSchema.parse + >[0], + ) { + const request = + TransitionRequestSchema.parse(input); + + if ( + await this.store.hasProcessedRequest( + request.requestId, + ) + ) { + return this.duplicateResult( + request.requestId, + request.workflowId, + request.principal.actor, + ); + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + const decision = combineDecisions( + assertStateTransitionShape( + workflow, + request.fromState, + request.toState, + ), + canRequestTransition( + request.principal, + request.fromState, + ), + evaluateWorkflowGates( + workflow, + request.fromState, + request.toState, + ), + ); + + if (!decision.allowed) { + await this.audit({ + auditId: this.auditId( + request.requestId, + 'transition-denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.transition', + outcome: 'denied', + reason: decision.reason, + workflowId: workflow.id, + workflowRevisionBefore: + workflow.revision, + workflowRevisionAfter: + workflow.revision, + metadata: { + fromState: request.fromState, + toState: request.toState, + missingRequirements: + decision.missingRequirements, + }, + }); + + throw new Error( + [ + decision.reason, + ...decision.missingRequirements, + ].join('|'), + ); + } + + const before = workflow.revision; + const now = this.clock(); + + workflow = { + ...workflow, + state: request.toState, + revision: before + 1, + updatedAt: now, + }; + + workflow = + InvestmentWorkflowSchema.parse( + workflow, + ); + + const saved = + await this.store.replaceWorkflow({ + workflow, + expectedRevision: before, + }); + + await this.store.markProcessedRequest( + request.requestId, + ); + + await this.audit({ + auditId: this.auditId( + request.requestId, + 'transitioned', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.transition', + outcome: 'transitioned', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + fromState: request.fromState, + toState: request.toState, + transitionAuthority: + 'control_plane_only', + }, + }); + + return { + workflow: saved, + duplicate: false as const, + }; + } + + async recordInvalidation( + input: Parameters< + typeof RecordInvalidationRequestSchema.parse + >[0], + ) { + const request = + RecordInvalidationRequestSchema.parse( + input, + ); + + if ( + await this.store.hasProcessedRequest( + request.requestId, + ) + ) { + return this.duplicateResult( + request.requestId, + request.workflowId, + request.principal.actor, + ); + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + const permission = + canRecordMaterialInvalidation( + request.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + if ( + request.invalidation.workflowId !== + workflow.id + ) { + throw new Error( + 'invalidation_workflow_id_mismatch', + ); + } + + if ( + request.invalidation.recordedBy.id !== + request.principal.actor.id || + request.invalidation.recordedBy.kind !== + request.principal.actor.kind + ) { + throw new Error( + 'invalidation_recorder_must_match_request_principal', + ); + } + + if ( + workflow.invalidations.some( + (item) => + item.id === + request.invalidation.id, + ) + ) { + throw new Error( + `invalidation_id_already_exists:${request.invalidation.id}`, + ); + } + + const before = workflow.revision; + + workflow = { + ...workflow, + revision: before + 1, + updatedAt: this.clock(), + invalidations: [ + ...workflow.invalidations, + request.invalidation, + ], + }; + + workflow = + InvestmentWorkflowSchema.parse( + workflow, + ); + + const saved = + await this.store.replaceWorkflow({ + workflow, + expectedRevision: before, + }); + + await this.store.markProcessedRequest( + request.requestId, + ); + + await this.audit({ + auditId: this.auditId( + request.requestId, + 'invalidation', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: + 'workflow.record_invalidation', + outcome: 'recorded', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + invalidationId: + request.invalidation.id, + invalidationKind: + request.invalidation.kind, + }, + }); + + return { + workflow: saved, + duplicate: false as const, + }; + } + + async resolveInvalidation( + input: Parameters< + typeof ResolveInvalidationRequestSchema.parse + >[0], + ) { + const request = + ResolveInvalidationRequestSchema.parse( + input, + ); + + if ( + await this.store.hasProcessedRequest( + request.requestId, + ) + ) { + return this.duplicateResult( + request.requestId, + request.workflowId, + request.principal.actor, + ); + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + const permission = + canResolveMaterialInvalidation( + request.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + const target = + workflow.invalidations.find( + (item) => + item.id === + request.invalidationId, + ); + + if (!target) { + throw new Error( + `invalidation_not_found:${request.invalidationId}`, + ); + } + + if (target.status === 'resolved') { + throw new Error( + `invalidation_already_resolved:${request.invalidationId}`, + ); + } + + const before = workflow.revision; + const now = this.clock(); + + workflow = { + ...workflow, + revision: before + 1, + updatedAt: now, + invalidations: + workflow.invalidations.map( + (item) => + item.id === + request.invalidationId + ? { + ...item, + status: + 'resolved' as const, + resolvedBy: + request.principal.actor, + resolvedAt: now, + resolutionReason: + request.reason, + } + : item, + ), + }; + + workflow = + InvestmentWorkflowSchema.parse( + workflow, + ); + + const saved = + await this.store.replaceWorkflow({ + workflow, + expectedRevision: before, + }); + + await this.store.markProcessedRequest( + request.requestId, + ); + + await this.audit({ + auditId: this.auditId( + request.requestId, + 'invalidation-resolved', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: + 'workflow.resolve_invalidation', + outcome: 'recorded', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + invalidationId: + request.invalidationId, + }, + }); + + return { + workflow: saved, + duplicate: false as const, + }; + } + + async authorizeFinancialAction( + input: Parameters< + typeof FinancialActionRequestSchema.parse + >[0], + ) { + const request = + FinancialActionRequestSchema.parse( + input, + ); + + const permission = + canAuthorizeFinancialAction( + request.principal, + request.action, + ); + + await this.audit({ + auditId: this.auditId( + request.requestId, + permission.allowed + ? 'financial-authorized' + : 'financial-denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: + `financial.${request.action}`, + outcome: permission.allowed + ? 'authorized' + : 'denied', + reason: permission.reason, + workflowId: request.workflowId, + metadata: { + financialAction: + request.action, + }, + }); + + return permission; + } + + async getWorkflow( + workflowId: string, + ) { + return this.requireWorkflow( + workflowId, + ); + } + + async listAudit( + workflowId?: string, + ) { + return this.store.listAudit( + workflowId, + ); + } +} diff --git a/lib/control-plane/gates.ts b/lib/control-plane/gates.ts new file mode 100644 index 00000000..8120d81d --- /dev/null +++ b/lib/control-plane/gates.ts @@ -0,0 +1,356 @@ +import type { + AuthorizationDecision, + InvestmentWorkflow, + InvestmentWorkflowState, + WorkflowArtifact, +} from '@/lib/control-plane/schema'; + +function activeArtifacts( + workflow: InvestmentWorkflow, +): WorkflowArtifact[] { + return workflow.artifacts.filter( + (artifact) => artifact.status === 'active', + ); +} + +function hasArtifact( + workflow: InvestmentWorkflow, + kind: WorkflowArtifact['kind'], + options: { + authorId?: string; + metadataEquals?: Record; + } = {}, +): boolean { + return activeArtifacts(workflow).some( + (artifact) => { + if (artifact.kind !== kind) { + return false; + } + + if ( + options.authorId && + artifact.createdBy.id !== options.authorId + ) { + return false; + } + + if (options.metadataEquals) { + for (const [ + key, + value, + ] of Object.entries( + options.metadataEquals, + )) { + if (artifact.metadata[key] !== value) { + return false; + } + } + } + + return true; + }, + ); +} + +function missing( + requirements: string[], +): AuthorizationDecision { + return { + allowed: requirements.length === 0, + reason: + requirements.length === 0 + ? 'workflow_gates_satisfied' + : 'workflow_gates_not_satisfied', + missingRequirements: requirements, + }; +} + +export function evaluateWorkflowGates( + workflow: InvestmentWorkflow, + from: InvestmentWorkflowState, + to: InvestmentWorkflowState, +): AuthorizationDecision { + const requirements: string[] = []; + + const require = ( + condition: boolean, + code: string, + ) => { + if (!condition) { + requirements.push(code); + } + }; + + if ( + from === 'RESEARCHING' && + to === 'READY_FOR_RED_DESK' + ) { + require( + hasArtifact( + workflow, + 'research_proposal', + ), + 'research_proposal_required', + ); + } + + if ( + from === 'UNDER_CRITICAL_REVIEW' && + to === + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR' + ) { + require( + hasArtifact( + workflow, + 'red_desk_review', + { authorId: 'yann' }, + ), + 'yann_red_desk_review_required', + ); + } + + if ( + from === + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR' && + to === 'WAITING_CEO_RESEARCH_DECISION' + ) { + require( + hasArtifact( + workflow, + 'final_research_brief', + { authorId: 'beppe' }, + ), + 'beppe_final_research_brief_required', + ); + } + + if ( + from === 'WAITING_CEO_RESEARCH_DECISION' && + to === 'CEO_RESEARCH_APPROVED' + ) { + require( + hasArtifact( + workflow, + 'ceo_research_decision', + { + authorId: 'ceo', + metadataEquals: { + decision: 'approved', + }, + }, + ), + 'ceo_research_approval_record_required', + ); + } + + if ( + from === 'WAITING_CEO_RESEARCH_DECISION' && + to === 'CEO_RESEARCH_REJECTED' + ) { + require( + hasArtifact( + workflow, + 'ceo_research_decision', + { + authorId: 'ceo', + metadataEquals: { + decision: 'rejected', + }, + }, + ), + 'ceo_research_rejection_record_required', + ); + } + + if ( + from === 'CEO_RESEARCH_APPROVED' && + to === 'RISK_ANALYSIS' + ) { + require( + hasArtifact( + workflow, + 'ceo_research_decision', + { + authorId: 'ceo', + metadataEquals: { + decision: 'approved', + }, + }, + ), + 'approved_ceo_research_decision_required', + ); + } + + if ( + from === 'RISK_ANALYSIS' && + to === 'RISK_REVIEW' + ) { + require( + hasArtifact( + workflow, + 'portfolio_risk_assessment', + { authorId: 'manuel' }, + ), + 'manuel_portfolio_risk_assessment_required', + ); + + require( + hasArtifact( + workflow, + 'trade_structure', + { authorId: 'dimash' }, + ), + 'dimash_trade_structure_required', + ); + + require( + hasArtifact( + workflow, + 'liquidity_event_assessment', + { authorId: 'bare' }, + ), + 'bare_liquidity_event_assessment_required', + ); + + require( + hasArtifact( + workflow, + 'broker_execution_instructions', + { authorId: 'angelo' }, + ), + 'angelo_broker_execution_instructions_required', + ); + } + + if ( + from === 'RISK_REVIEW' && + to === 'RISK_APPROVED' + ) { + require( + hasArtifact( + workflow, + 'independent_risk_verdict', + { + authorId: 'pio', + metadataEquals: { + verdict: 'Approved', + }, + }, + ), + 'pio_approved_verdict_required', + ); + + require( + hasArtifact( + workflow, + 'final_risk_ticket', + { authorId: 'christian' }, + ), + 'christian_final_risk_ticket_required', + ); + } + + if ( + from === 'RISK_REVIEW' && + to === 'RISK_MODIFICATION_REQUIRED' + ) { + require( + hasArtifact( + workflow, + 'independent_risk_verdict', + { + authorId: 'pio', + metadataEquals: { + verdict: + 'Approved_with_Modifications', + }, + }, + ), + 'pio_modification_verdict_required', + ); + } + + if ( + from === 'RISK_REVIEW' && + to === 'RISK_REJECTED' + ) { + require( + hasArtifact( + workflow, + 'independent_risk_verdict', + { + authorId: 'pio', + metadataEquals: { + verdict: 'Rejected', + }, + }, + ), + 'pio_rejection_verdict_required', + ); + } + + if ( + from === 'RISK_APPROVED' && + to === 'WAITING_CEO_EXECUTION' + ) { + require( + hasArtifact( + workflow, + 'final_risk_ticket', + { authorId: 'christian' }, + ), + 'final_risk_ticket_required', + ); + } + + if ( + from === 'WAITING_CEO_EXECUTION' && + to === 'CEO_EXECUTION_CONFIRMED' + ) { + require( + hasArtifact( + workflow, + 'ceo_execution_confirmation', + { authorId: 'ceo' }, + ), + 'ceo_execution_confirmation_required', + ); + + require( + !workflow.invalidations.some( + (invalidation) => + invalidation.status === 'active', + ), + 'active_material_invalidation_blocks_execution_confirmation', + ); + } + + if ( + from === 'CEO_EXECUTION_CONFIRMED' && + to === 'MONITORING' + ) { + require( + hasArtifact( + workflow, + 'ceo_execution_confirmation', + { authorId: 'ceo' }, + ), + 'execution_confirmation_record_required', + ); + } + + if ( + from === 'POST_MORTEM' && + to === 'ARCHIVED' + ) { + require( + hasArtifact( + workflow, + 'post_mortem', + ), + 'post_mortem_record_required', + ); + } + + return missing(requirements); +} diff --git a/lib/control-plane/index.ts b/lib/control-plane/index.ts new file mode 100644 index 00000000..ad3e169e --- /dev/null +++ b/lib/control-plane/index.ts @@ -0,0 +1,9 @@ +export * from '@/lib/control-plane/schema'; +export * from '@/lib/control-plane/spec'; +export * from '@/lib/control-plane/state-machine'; +export * from '@/lib/control-plane/permissions'; +export * from '@/lib/control-plane/gates'; +export * from '@/lib/control-plane/store'; +export * from '@/lib/control-plane/jobs'; +export * from '@/lib/control-plane/brain-bridge'; +export * from '@/lib/control-plane/engine'; diff --git a/lib/control-plane/jobs.ts b/lib/control-plane/jobs.ts new file mode 100644 index 00000000..14176124 --- /dev/null +++ b/lib/control-plane/jobs.ts @@ -0,0 +1,111 @@ +import { z } from 'zod'; + +import { + TimestampSchema, +} from '@/lib/brain/core-schema'; + +export const RetryPolicySchema = z.object({ + maxAttempts: z.number().int().positive(), + initialDelayMs: z.number().int().min(0), + backoffMultiplier: z.number().finite().min(1), + maxDelayMs: z.number().int().min(0), + timeoutMs: z.number().int().positive(), +}); + +export const ScheduledJobStatusSchema = z.enum([ + 'scheduled', + 'running', + 'succeeded', + 'failed', + 'cancelled', + 'timed_out', +]); + +export const ScheduledJobSchema = z.object({ + id: z.string().min(1), + workflowId: z.string().min(1).optional(), + kind: z.string().min(1), + runAt: TimestampSchema, + status: ScheduledJobStatusSchema.default( + 'scheduled', + ), + attempts: z.number().int().min(0).default(0), + startedAt: TimestampSchema.optional(), + completedAt: TimestampSchema.optional(), + retryPolicy: RetryPolicySchema, + metadata: z.record(z.unknown()).default({}), +}); + +export type RetryPolicy = z.infer< + typeof RetryPolicySchema +>; + +export type ScheduledJob = z.infer< + typeof ScheduledJobSchema +>; + +export function computeRetryDelayMs( + policy: RetryPolicy, + failedAttemptNumber: number, +): number { + if (failedAttemptNumber <= 0) { + return 0; + } + + const raw = + policy.initialDelayMs * + Math.pow( + policy.backoffMultiplier, + failedAttemptNumber - 1, + ); + + return Math.min( + policy.maxDelayMs, + Math.round(raw), + ); +} + +export function canRetryJob( + job: ScheduledJob, +): boolean { + return ( + job.status === 'failed' && + job.attempts < job.retryPolicy.maxAttempts + ); +} + +export function isJobTimedOut( + job: ScheduledJob, + now: string, +): boolean { + if ( + job.status !== 'running' || + !job.startedAt + ) { + return false; + } + + return ( + Date.parse(now) - + Date.parse(job.startedAt) >= + job.retryPolicy.timeoutMs + ); +} + +export function nextRetryAt( + job: ScheduledJob, + now: string, +): string | null { + if (!canRetryJob(job)) { + return null; + } + + const delay = computeRetryDelayMs( + job.retryPolicy, + job.attempts, + ); + + return new Date( + Date.parse(now) + delay, + ).toISOString(); +} diff --git a/lib/control-plane/permissions.ts b/lib/control-plane/permissions.ts new file mode 100644 index 00000000..91b5275c --- /dev/null +++ b/lib/control-plane/permissions.ts @@ -0,0 +1,263 @@ +import type { + AuthorizationDecision, + ControlPlanePrincipal, + FinancialAction, + InvestmentWorkflowState, + WorkflowArtifactKind, +} from '@/lib/control-plane/schema'; + +import { + ARTIFACT_AUTHORS, + CEO_GATED_SOURCE_STATES, + CEO_ID, + MONITORING_AGENT_IDS, + MONITORING_STATES, + RESEARCH_AGENT_IDS, + RESEARCH_STATES, + RISK_AGENT_IDS, + RISK_STATES, + MATERIAL_INVALIDATION_RECORDER_IDS, +} from '@/lib/control-plane/spec'; + +function allow(reason: string): AuthorizationDecision { + return { + allowed: true, + reason, + missingRequirements: [], + }; +} + +function deny( + reason: string, + missingRequirements: string[] = [], +): AuthorizationDecision { + return { + allowed: false, + reason, + missingRequirements, + }; +} + +export function isCeo( + principal: ControlPlanePrincipal, +): boolean { + return ( + principal.actor.kind === 'human' && + principal.actor.id === CEO_ID + ); +} + +export function isControlPlaneInternal( + principal: ControlPlanePrincipal, +): boolean { + return ( + principal.actor.kind === 'control_plane' || + principal.actor.kind === 'system' + ); +} + +function inIds( + id: string, + ids: readonly string[], +): boolean { + return ids.includes(id); +} + +export function canCreateInvestmentWorkflow( + principal: ControlPlanePrincipal, + responsibleResearchAgentId?: string, +): AuthorizationDecision { + if (isControlPlaneInternal(principal)) { + return allow('control_plane_may_create_workflow'); + } + + if ( + principal.actor.kind === 'agent' && + inIds( + principal.actor.id, + ['lauti', 'pepo', 'andy'], + ) && + ( + responsibleResearchAgentId === undefined || + responsibleResearchAgentId === principal.actor.id + ) + ) { + return allow( + 'authorized_research_preparer_may_request_workflow_creation', + ); + } + + if (isCeo(principal)) { + return allow( + 'ceo_ultimate_authority_may_request_workflow_creation', + ); + } + + return deny( + 'principal_not_authorized_to_create_investment_workflow', + ); +} + +export function canRegisterArtifact( + principal: ControlPlanePrincipal, + kind: WorkflowArtifactKind, +): AuthorizationDecision { + if (isControlPlaneInternal(principal)) { + return allow( + 'control_plane_internal_artifact_registration_allowed', + ); + } + + const allowedIds = ARTIFACT_AUTHORS[kind]; + + if ( + allowedIds.includes(principal.actor.id) + ) { + return allow( + `artifact_author_allowed:${kind}`, + ); + } + + return deny( + `artifact_author_denied:${kind}`, + ); +} + +export function canRequestTransition( + principal: ControlPlanePrincipal, + from: InvestmentWorkflowState, +): AuthorizationDecision { + if (isControlPlaneInternal(principal)) { + return allow( + 'control_plane_internal_transition_request_allowed', + ); + } + + if (CEO_GATED_SOURCE_STATES.has(from)) { + return isCeo(principal) + ? allow('ceo_gated_transition_allowed') + : deny('ceo_required_for_transition'); + } + + if (isCeo(principal)) { + return allow( + 'ceo_may_request_transition_subject_to_all_gates', + ); + } + + if (principal.actor.kind !== 'agent') { + return deny( + 'non_agent_principal_not_authorized_for_stage_transition', + ); + } + + if ( + RESEARCH_STATES.has(from) && + inIds(principal.actor.id, RESEARCH_AGENT_IDS) + ) { + return allow( + 'research_stage_transition_request_allowed', + ); + } + + if ( + RISK_STATES.has(from) && + inIds(principal.actor.id, RISK_AGENT_IDS) + ) { + return allow( + 'risk_stage_transition_request_allowed', + ); + } + + if ( + MONITORING_STATES.has(from) && + inIds( + principal.actor.id, + MONITORING_AGENT_IDS, + ) + ) { + return allow( + 'monitoring_stage_transition_request_allowed', + ); + } + + return deny( + 'principal_department_not_authorized_for_current_stage', + ); +} + +export function canRecordMaterialInvalidation( + principal: ControlPlanePrincipal, +): AuthorizationDecision { + if (isControlPlaneInternal(principal)) { + return allow( + 'control_plane_internal_invalidation_allowed', + ); + } + + if ( + principal.actor.kind === 'agent' && + inIds( + principal.actor.id, + MATERIAL_INVALIDATION_RECORDER_IDS, + ) + ) { + return allow( + 'authorized_risk_or_monitoring_agent_may_record_invalidation', + ); + } + + if (isCeo(principal)) { + return allow( + 'ceo_may_record_material_invalidation', + ); + } + + return deny( + 'principal_not_authorized_to_record_material_invalidation', + ); +} + +export function canResolveMaterialInvalidation( + principal: ControlPlanePrincipal, +): AuthorizationDecision { + if (isControlPlaneInternal(principal)) { + return allow( + 'control_plane_internal_invalidation_resolution_allowed', + ); + } + + if ( + principal.actor.kind === 'agent' && + principal.actor.id === 'christian' + ) { + return allow( + 'final_risk_supervisor_may_request_invalidation_resolution', + ); + } + + if (isCeo(principal)) { + return allow( + 'ceo_may_request_invalidation_resolution', + ); + } + + return deny( + 'principal_not_authorized_to_resolve_material_invalidation', + ); +} + +export function canAuthorizeFinancialAction( + principal: ControlPlanePrincipal, + _action: FinancialAction, +): AuthorizationDecision { + if (isCeo(principal)) { + return allow( + 'financial_execution_reserved_for_human_ceo', + ); + } + + return deny( + 'financial_execution_reserved_for_human_ceo', + ); +} diff --git a/lib/control-plane/schema.ts b/lib/control-plane/schema.ts new file mode 100644 index 00000000..53035ddf --- /dev/null +++ b/lib/control-plane/schema.ts @@ -0,0 +1,279 @@ +import { z } from 'zod'; + +import { + BrainActorSchema, + TimestampSchema, +} from '@/lib/brain/core-schema'; + +export const InvestmentWorkflowStateSchema = z.enum([ + 'DRAFT', + 'RESEARCHING', + 'READY_FOR_RED_DESK', + 'UNDER_CRITICAL_REVIEW', + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR', + 'WAITING_CEO_RESEARCH_DECISION', + 'CEO_RESEARCH_REJECTED', + 'CEO_RESEARCH_APPROVED', + 'RISK_ANALYSIS', + 'RISK_REVIEW', + 'RISK_REJECTED', + 'RISK_MODIFICATION_REQUIRED', + 'RISK_APPROVED', + 'WAITING_CEO_EXECUTION', + 'CEO_EXECUTION_CONFIRMED', + 'MONITORING', + 'CLOSED', + 'POST_MORTEM', + 'ARCHIVED', +]); + +export const WorkflowArtifactKindSchema = z.enum([ + 'research_proposal', + 'red_desk_review', + 'final_research_brief', + 'ceo_research_decision', + + 'portfolio_risk_assessment', + 'trade_structure', + 'liquidity_event_assessment', + 'broker_execution_instructions', + 'independent_risk_verdict', + 'final_risk_ticket', + + 'ceo_execution_confirmation', + + 'position_monitoring_record', + 'portfolio_exposure_record', + 'performance_evaluation', + 'employee_kpi_report', + 'process_learning_recommendation', + 'final_monitoring_report', + + 'closure_record', + 'post_mortem', + 'correction', +]); + +export const WorkflowArtifactStatusSchema = z.enum([ + 'active', + 'superseded', + 'archived', +]); + +export const WorkflowArtifactSchema = z.object({ + id: z.string().min(1), + workflowId: z.string().min(1), + kind: WorkflowArtifactKindSchema, + createdBy: BrainActorSchema, + createdAt: TimestampSchema, + summary: z.string().min(1), + status: WorkflowArtifactStatusSchema.default('active'), + metadata: z.record(z.unknown()).default({}), +}); + +export const InvalidationKindSchema = z.enum([ + 'material_price_change', + 'material_volatility_change', + 'material_news_change', + 'material_portfolio_change', + 'material_event_change', + 'data_staleness', + 'other', +]); + +export const WorkflowInvalidationStatusSchema = z.enum([ + 'active', + 'resolved', +]); + +export const WorkflowInvalidationSchema = z.object({ + id: z.string().min(1), + workflowId: z.string().min(1), + kind: InvalidationKindSchema, + status: WorkflowInvalidationStatusSchema.default('active'), + reason: z.string().min(1), + recordedBy: BrainActorSchema, + recordedAt: TimestampSchema, + resolvedBy: BrainActorSchema.optional(), + resolvedAt: TimestampSchema.optional(), + resolutionReason: z.string().min(1).optional(), + metadata: z.record(z.unknown()).default({}), +}); + +export const InvestmentWorkflowSchema = z.object({ + id: z.string().min(1), + state: InvestmentWorkflowStateSchema, + revision: z.number().int().min(0), + createdBy: BrainActorSchema, + createdAt: TimestampSchema, + updatedAt: TimestampSchema, + + responsibleResearchAgentId: z.string().min(1).optional(), + assetRef: z.string().min(1).optional(), + + artifacts: z.array(WorkflowArtifactSchema).default([]), + invalidations: z.array(WorkflowInvalidationSchema).default([]), + + metadata: z.record(z.unknown()).default({}), +}); + +export const ControlPlanePrincipalSchema = z.object({ + actor: BrainActorSchema, + sessionId: z.string().min(1).optional(), +}); + +export const CreateWorkflowRequestSchema = z.object({ + requestId: z.string().min(1), + workflowId: z.string().min(1), + principal: ControlPlanePrincipalSchema, + responsibleResearchAgentId: z.string().min(1).optional(), + assetRef: z.string().min(1).optional(), + reason: z.string().min(1), + metadata: z.record(z.unknown()).default({}), +}); + +export const RegisterArtifactRequestSchema = z.object({ + requestId: z.string().min(1), + workflowId: z.string().min(1), + principal: ControlPlanePrincipalSchema, + expectedRevision: z.number().int().min(0).optional(), + artifact: WorkflowArtifactSchema, + reason: z.string().min(1), +}); + +export const TransitionRequestSchema = z.object({ + requestId: z.string().min(1), + workflowId: z.string().min(1), + principal: ControlPlanePrincipalSchema, + fromState: InvestmentWorkflowStateSchema, + toState: InvestmentWorkflowStateSchema, + expectedRevision: z.number().int().min(0).optional(), + reason: z.string().min(1), +}); + +export const RecordInvalidationRequestSchema = z.object({ + requestId: z.string().min(1), + workflowId: z.string().min(1), + principal: ControlPlanePrincipalSchema, + expectedRevision: z.number().int().min(0).optional(), + invalidation: WorkflowInvalidationSchema, + reason: z.string().min(1), +}); + +export const ResolveInvalidationRequestSchema = z.object({ + requestId: z.string().min(1), + workflowId: z.string().min(1), + principal: ControlPlanePrincipalSchema, + expectedRevision: z.number().int().min(0).optional(), + invalidationId: z.string().min(1), + reason: z.string().min(1), +}); + +export const FinancialActionSchema = z.enum([ + 'buy', + 'sell', + 'deposit', + 'withdraw', + 'modify_order', + 'cancel_order', +]); + +export const FinancialActionRequestSchema = z.object({ + requestId: z.string().min(1), + workflowId: z.string().min(1).optional(), + principal: ControlPlanePrincipalSchema, + action: FinancialActionSchema, + reason: z.string().min(1), +}); + +export const ControlPlaneAuditOutcomeSchema = z.enum([ + 'allowed', + 'denied', + 'created', + 'recorded', + 'transitioned', + 'authorized', + 'rejected', + 'duplicate', + 'failed', +]); + +export const ControlPlaneAuditRecordSchema = z.object({ + auditId: z.string().min(1), + requestId: z.string().min(1), + at: TimestampSchema, + actor: BrainActorSchema, + action: z.string().min(1), + outcome: ControlPlaneAuditOutcomeSchema, + reason: z.string().default(''), + workflowId: z.string().min(1).optional(), + workflowRevisionBefore: z.number().int().min(0).optional(), + workflowRevisionAfter: z.number().int().min(0).optional(), + metadata: z.record(z.unknown()).default({}), +}); + +export const AuthorizationDecisionSchema = z.object({ + allowed: z.boolean(), + reason: z.string().min(1), + missingRequirements: z.array(z.string().min(1)).default([]), +}); + +export type InvestmentWorkflowState = z.infer< + typeof InvestmentWorkflowStateSchema +>; + +export type WorkflowArtifactKind = z.infer< + typeof WorkflowArtifactKindSchema +>; + +export type WorkflowArtifact = z.infer< + typeof WorkflowArtifactSchema +>; + +export type WorkflowInvalidation = z.infer< + typeof WorkflowInvalidationSchema +>; + +export type InvestmentWorkflow = z.infer< + typeof InvestmentWorkflowSchema +>; + +export type ControlPlanePrincipal = z.infer< + typeof ControlPlanePrincipalSchema +>; + +export type CreateWorkflowRequestInput = z.input< + typeof CreateWorkflowRequestSchema +>; + +export type RegisterArtifactRequestInput = z.input< + typeof RegisterArtifactRequestSchema +>; + +export type TransitionRequestInput = z.input< + typeof TransitionRequestSchema +>; + +export type RecordInvalidationRequestInput = z.input< + typeof RecordInvalidationRequestSchema +>; + +export type ResolveInvalidationRequestInput = z.input< + typeof ResolveInvalidationRequestSchema +>; + +export type FinancialAction = z.infer< + typeof FinancialActionSchema +>; + +export type FinancialActionRequestInput = z.input< + typeof FinancialActionRequestSchema +>; + +export type ControlPlaneAuditRecord = z.infer< + typeof ControlPlaneAuditRecordSchema +>; + +export type AuthorizationDecision = z.infer< + typeof AuthorizationDecisionSchema +>; diff --git a/lib/control-plane/spec.ts b/lib/control-plane/spec.ts new file mode 100644 index 00000000..d2317e61 --- /dev/null +++ b/lib/control-plane/spec.ts @@ -0,0 +1,212 @@ +import type { + InvestmentWorkflowState, + WorkflowArtifactKind, +} from '@/lib/control-plane/schema'; + +export const CANONICAL_GOVERNANCE_VERSION = '1.0' as const; + +export const CEO_ID = 'ceo' as const; + +export const RESEARCH_AGENT_IDS = [ + 'djed', + 'marcus', + 'lauti', + 'pepo', + 'andy', + 'yann', + 'beppe', +] as const; + +export const RISK_AGENT_IDS = [ + 'manuel', + 'dimash', + 'bare', + 'angelo', + 'pio', + 'christian', +] as const; + +export const MONITORING_AGENT_IDS = [ + 'john', + 'ale', + 'carlos', + 'hakan', + 'zielu', + 'javier', +] as const; + +export const RESEARCH_PREPARER_IDS = [ + 'lauti', + 'pepo', + 'andy', +] as const; + +export const FINAL_SUPERVISORS = { + research: 'beppe', + risk: 'christian', + monitoring: 'javier', +} as const; + +export const INDEPENDENT_REVIEWERS = { + research: 'yann', + risk: 'pio', +} as const; + +export const INVESTMENT_WORKFLOW_TRANSITIONS: Record< + InvestmentWorkflowState, + readonly InvestmentWorkflowState[] +> = { + DRAFT: ['RESEARCHING'], + RESEARCHING: ['READY_FOR_RED_DESK'], + READY_FOR_RED_DESK: ['UNDER_CRITICAL_REVIEW'], + UNDER_CRITICAL_REVIEW: [ + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR', + ], + READY_FOR_FINAL_RESEARCH_SUPERVISOR: [ + 'WAITING_CEO_RESEARCH_DECISION', + ], + WAITING_CEO_RESEARCH_DECISION: [ + 'CEO_RESEARCH_REJECTED', + 'CEO_RESEARCH_APPROVED', + ], + CEO_RESEARCH_REJECTED: ['ARCHIVED'], + CEO_RESEARCH_APPROVED: ['RISK_ANALYSIS'], + RISK_ANALYSIS: ['RISK_REVIEW'], + RISK_REVIEW: [ + 'RISK_REJECTED', + 'RISK_MODIFICATION_REQUIRED', + 'RISK_APPROVED', + ], + RISK_REJECTED: ['ARCHIVED'], + RISK_MODIFICATION_REQUIRED: ['RISK_ANALYSIS'], + RISK_APPROVED: ['WAITING_CEO_EXECUTION'], + WAITING_CEO_EXECUTION: [ + 'CEO_EXECUTION_CONFIRMED', + ], + CEO_EXECUTION_CONFIRMED: ['MONITORING'], + MONITORING: ['CLOSED'], + CLOSED: ['POST_MORTEM'], + POST_MORTEM: ['ARCHIVED'], + ARCHIVED: [], +}; + +export const CEO_GATED_SOURCE_STATES = new Set< + InvestmentWorkflowState +>([ + 'WAITING_CEO_RESEARCH_DECISION', + 'WAITING_CEO_EXECUTION', +]); + +export const RESEARCH_STATES = new Set< + InvestmentWorkflowState +>([ + 'DRAFT', + 'RESEARCHING', + 'READY_FOR_RED_DESK', + 'UNDER_CRITICAL_REVIEW', + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR', + 'WAITING_CEO_RESEARCH_DECISION', + 'CEO_RESEARCH_REJECTED', + 'CEO_RESEARCH_APPROVED', +]); + +export const RISK_STATES = new Set< + InvestmentWorkflowState +>([ + 'RISK_ANALYSIS', + 'RISK_REVIEW', + 'RISK_REJECTED', + 'RISK_MODIFICATION_REQUIRED', + 'RISK_APPROVED', + 'WAITING_CEO_EXECUTION', +]); + +export const MONITORING_STATES = new Set< + InvestmentWorkflowState +>([ + 'CEO_EXECUTION_CONFIRMED', + 'MONITORING', + 'CLOSED', + 'POST_MORTEM', + 'ARCHIVED', +]); + +export const IMMUTABLE_HISTORICAL_ARTIFACTS = + new Set([ + 'research_proposal', + 'red_desk_review', + 'ceo_research_decision', + 'portfolio_risk_assessment', + 'trade_structure', + 'liquidity_event_assessment', + 'broker_execution_instructions', + 'independent_risk_verdict', + 'final_risk_ticket', + 'ceo_execution_confirmation', + 'employee_kpi_report', + ]); + +export const ARTIFACT_AUTHORS: Record< + WorkflowArtifactKind, + readonly string[] +> = { + research_proposal: [ + 'lauti', + 'pepo', + 'andy', + ], + red_desk_review: ['yann'], + final_research_brief: ['beppe'], + ceo_research_decision: ['ceo'], + + portfolio_risk_assessment: ['manuel'], + trade_structure: ['dimash'], + liquidity_event_assessment: ['bare'], + broker_execution_instructions: ['angelo'], + independent_risk_verdict: ['pio'], + final_risk_ticket: ['christian'], + + ceo_execution_confirmation: ['ceo'], + + position_monitoring_record: ['john'], + portfolio_exposure_record: ['ale'], + performance_evaluation: ['carlos'], + employee_kpi_report: ['hakan'], + process_learning_recommendation: ['zielu'], + final_monitoring_report: ['javier'], + + closure_record: ['javier'], + post_mortem: ['zielu', 'javier'], + + correction: [ + 'ceo', + 'beppe', + 'christian', + 'javier', + ], +}; + +export const FINANCIAL_EXECUTION_ACTIONS = [ + 'buy', + 'sell', + 'deposit', + 'withdraw', + 'modify_order', + 'cancel_order', +] as const; + +export const MATERIAL_INVALIDATION_RECORDER_IDS = [ + 'manuel', + 'bare', + 'pio', + 'christian', + 'john', + 'ale', + 'javier', +] as const; + +/** + * Numerical portfolio and trade risk limits are intentionally absent. + * Canonical governance declares numeric_limits_defined: false. + */ +export const NUMERIC_RISK_LIMITS_DEFINED = false as const; diff --git a/lib/control-plane/state-machine.ts b/lib/control-plane/state-machine.ts new file mode 100644 index 00000000..78e59e27 --- /dev/null +++ b/lib/control-plane/state-machine.ts @@ -0,0 +1,47 @@ +import type { + AuthorizationDecision, + InvestmentWorkflow, + InvestmentWorkflowState, +} from '@/lib/control-plane/schema'; + +import { + INVESTMENT_WORKFLOW_TRANSITIONS, +} from '@/lib/control-plane/spec'; + +export function canTransitionState( + from: InvestmentWorkflowState, + to: InvestmentWorkflowState, +): boolean { + return INVESTMENT_WORKFLOW_TRANSITIONS[ + from + ].includes(to); +} + +export function assertStateTransitionShape( + workflow: InvestmentWorkflow, + from: InvestmentWorkflowState, + to: InvestmentWorkflowState, +): AuthorizationDecision { + const missingRequirements: string[] = []; + + if (workflow.state !== from) { + missingRequirements.push( + `workflow_state_is_${workflow.state}_not_${from}`, + ); + } + + if (!canTransitionState(from, to)) { + missingRequirements.push( + `transition_not_allowed:${from}->${to}`, + ); + } + + return { + allowed: missingRequirements.length === 0, + reason: + missingRequirements.length === 0 + ? 'transition_shape_allowed' + : 'transition_shape_denied', + missingRequirements, + }; +} diff --git a/lib/control-plane/store.ts b/lib/control-plane/store.ts new file mode 100644 index 00000000..ca3ef372 --- /dev/null +++ b/lib/control-plane/store.ts @@ -0,0 +1,155 @@ +import { + ControlPlaneAuditRecordSchema, + InvestmentWorkflowSchema, + type ControlPlaneAuditRecord, + type InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +export interface ControlPlaneStore { + getWorkflow( + workflowId: string, + ): Promise; + + createWorkflow( + workflow: InvestmentWorkflow, + ): Promise; + + replaceWorkflow(input: { + workflow: InvestmentWorkflow; + expectedRevision: number; + }): Promise; + + hasProcessedRequest( + requestId: string, + ): Promise; + + markProcessedRequest( + requestId: string, + ): Promise; + + appendAudit( + record: ControlPlaneAuditRecord, + ): Promise; + + listAudit( + workflowId?: string, + ): Promise; +} + +export class InMemoryControlPlaneStore + implements ControlPlaneStore +{ + private readonly workflows = + new Map(); + + private readonly processedRequests = + new Set(); + + private readonly audit: ControlPlaneAuditRecord[] = + []; + + async getWorkflow( + workflowId: string, + ): Promise { + const workflow = + this.workflows.get(workflowId); + + return workflow + ? structuredClone(workflow) + : null; + } + + async createWorkflow( + workflowInput: InvestmentWorkflow, + ): Promise { + const workflow = + InvestmentWorkflowSchema.parse( + workflowInput, + ); + + if (this.workflows.has(workflow.id)) { + throw new Error( + `workflow_already_exists:${workflow.id}`, + ); + } + + this.workflows.set( + workflow.id, + structuredClone(workflow), + ); + + return structuredClone(workflow); + } + + async replaceWorkflow(input: { + workflow: InvestmentWorkflow; + expectedRevision: number; + }): Promise { + const current = + this.workflows.get(input.workflow.id); + + if (!current) { + throw new Error( + `workflow_not_found:${input.workflow.id}`, + ); + } + + if ( + current.revision !== + input.expectedRevision + ) { + throw new Error( + `workflow_revision_conflict:expected=${input.expectedRevision}:actual=${current.revision}`, + ); + } + + const parsed = + InvestmentWorkflowSchema.parse( + input.workflow, + ); + + this.workflows.set( + parsed.id, + structuredClone(parsed), + ); + + return structuredClone(parsed); + } + + async hasProcessedRequest( + requestId: string, + ): Promise { + return this.processedRequests.has( + requestId, + ); + } + + async markProcessedRequest( + requestId: string, + ): Promise { + this.processedRequests.add(requestId); + } + + async appendAudit( + record: ControlPlaneAuditRecord, + ): Promise { + this.audit.push( + ControlPlaneAuditRecordSchema.parse( + record, + ), + ); + } + + async listAudit( + workflowId?: string, + ): Promise { + const records = workflowId + ? this.audit.filter( + (record) => + record.workflowId === workflowId, + ) + : this.audit; + + return structuredClone(records); + } +} diff --git a/tests/control-plane-engine.test.ts b/tests/control-plane-engine.test.ts new file mode 100644 index 00000000..35c401a6 --- /dev/null +++ b/tests/control-plane-engine.test.ts @@ -0,0 +1,504 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + CompanyControlPlane, +} from '@/lib/control-plane/engine'; + +import { + InMemoryControlPlaneStore, +} from '@/lib/control-plane/store'; + +function actor( + kind: 'agent' | 'human' | 'system' | 'control_plane', + id: string, +) { + return { + actor: { kind, id }, + }; +} + +function cp() { + const store = + new InMemoryControlPlaneStore(); + + const engine = + new CompanyControlPlane( + store, + () => + '2026-01-01T00:00:00.000Z', + ); + + return { + engine, + store, + }; +} + +async function createResearchWorkflow() { + const ctx = cp(); + + await ctx.engine.createWorkflow({ + requestId: 'create-1', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + responsibleResearchAgentId: 'lauti', + assetRef: 'asset:example', + reason: 'Start equity research workflow.', + metadata: {}, + }); + + return ctx; +} + +describe('Company Control Plane engine', () => { + test('creates canonical workflows in DRAFT', async () => { + const { engine } = + await createResearchWorkflow(); + + const workflow = + await engine.getWorkflow('wf-1'); + + expect(workflow.state).toBe('DRAFT'); + expect(workflow.revision).toBe(0); + }); + + test('prevents skipping mandatory research gates', async () => { + const { engine } = + await createResearchWorkflow(); + + await engine.transition({ + requestId: 'to-research', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Begin research.', + }); + + await expect( + engine.transition({ + requestId: 'to-red-desk', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'RESEARCHING', + toState: 'READY_FOR_RED_DESK', + expectedRevision: 1, + reason: 'Send to Red Desk.', + }), + ).rejects.toThrow( + 'research_proposal_required', + ); + }); + + test('accepts append-only research artifact then unlocks next gate', async () => { + const { engine } = + await createResearchWorkflow(); + + await engine.transition({ + requestId: 'to-research', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Begin research.', + }); + + await engine.registerArtifact({ + requestId: 'proposal', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + expectedRevision: 1, + artifact: { + id: 'artifact-proposal', + workflowId: 'wf-1', + kind: 'research_proposal', + createdBy: { + kind: 'agent', + id: 'lauti', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + summary: 'Equity proposal.', + metadata: {}, + }, + reason: 'Persist original proposal.', + }); + + const result = + await engine.transition({ + requestId: 'to-red-desk', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'RESEARCHING', + toState: 'READY_FOR_RED_DESK', + expectedRevision: 2, + reason: 'Proposal complete.', + }); + + expect(result.workflow.state).toBe( + 'READY_FOR_RED_DESK', + ); + }); + + test('CEO-only decisions cannot be performed by an agent', async () => { + const { engine, store } = cp(); + + await store.createWorkflow({ + id: 'wf-ceo', + state: + 'WAITING_CEO_RESEARCH_DECISION', + revision: 0, + createdBy: { + kind: 'control_plane', + id: 'cp', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + updatedAt: + '2026-01-01T00:00:00.000Z', + artifacts: [ + { + id: 'ceo-decision', + workflowId: 'wf-ceo', + kind: 'ceo_research_decision', + createdBy: { + kind: 'human', + id: 'ceo', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + summary: 'Approved.', + status: 'active', + metadata: { + decision: 'approved', + }, + }, + ], + invalidations: [], + metadata: {}, + }); + + await expect( + engine.transition({ + requestId: 'fake-ceo', + workflowId: 'wf-ceo', + principal: actor( + 'agent', + 'beppe', + ), + fromState: + 'WAITING_CEO_RESEARCH_DECISION', + toState: + 'CEO_RESEARCH_APPROVED', + expectedRevision: 0, + reason: 'Attempt bypass.', + }), + ).rejects.toThrow( + 'ceo_required_for_transition', + ); + + const approved = + await engine.transition({ + requestId: 'real-ceo', + workflowId: 'wf-ceo', + principal: actor( + 'human', + 'ceo', + ), + fromState: + 'WAITING_CEO_RESEARCH_DECISION', + toState: + 'CEO_RESEARCH_APPROVED', + expectedRevision: 0, + reason: 'Human CEO approved.', + }); + + expect(approved.workflow.state).toBe( + 'CEO_RESEARCH_APPROVED', + ); + }); + + test('all four mandatory risk analyses are required before risk review', async () => { + const { engine, store } = cp(); + + await store.createWorkflow({ + id: 'wf-risk', + state: 'RISK_ANALYSIS', + revision: 0, + createdBy: { + kind: 'control_plane', + id: 'cp', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + updatedAt: + '2026-01-01T00:00:00.000Z', + artifacts: [], + invalidations: [], + metadata: {}, + }); + + await expect( + engine.transition({ + requestId: 'risk-review', + workflowId: 'wf-risk', + principal: actor( + 'agent', + 'christian', + ), + fromState: 'RISK_ANALYSIS', + toState: 'RISK_REVIEW', + expectedRevision: 0, + reason: 'Request review.', + }), + ).rejects.toThrow( + 'manuel_portfolio_risk_assessment_required', + ); + }); + + test('active material invalidation blocks CEO execution confirmation', async () => { + const { engine, store } = cp(); + + await store.createWorkflow({ + id: 'wf-exec', + state: + 'WAITING_CEO_EXECUTION', + revision: 0, + createdBy: { + kind: 'control_plane', + id: 'cp', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + updatedAt: + '2026-01-01T00:00:00.000Z', + artifacts: [ + { + id: 'confirmation', + workflowId: 'wf-exec', + kind: + 'ceo_execution_confirmation', + createdBy: { + kind: 'human', + id: 'ceo', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + summary: 'Execution confirmed.', + status: 'active', + metadata: {}, + }, + ], + invalidations: [ + { + id: 'inv-1', + workflowId: 'wf-exec', + kind: + 'material_price_change', + status: 'active', + reason: + 'Material price movement.', + recordedBy: { + kind: 'agent', + id: 'john', + }, + recordedAt: + '2026-01-01T00:00:00.000Z', + metadata: {}, + }, + ], + metadata: {}, + }); + + await expect( + engine.transition({ + requestId: 'confirm-exec', + workflowId: 'wf-exec', + principal: actor( + 'human', + 'ceo', + ), + fromState: + 'WAITING_CEO_EXECUTION', + toState: + 'CEO_EXECUTION_CONFIRMED', + expectedRevision: 0, + reason: 'Confirm.', + }), + ).rejects.toThrow( + 'active_material_invalidation_blocks_execution_confirmation', + ); + }); + + test('only the human CEO is authorized for financial execution actions', async () => { + const { engine } = cp(); + + const agent = + await engine.authorizeFinancialAction({ + requestId: 'agent-buy', + principal: actor( + 'agent', + 'angelo', + ), + action: 'buy', + reason: 'Attempt execution.', + }); + + expect(agent.allowed).toBe(false); + + const ceo = + await engine.authorizeFinancialAction({ + requestId: 'ceo-buy', + principal: actor( + 'human', + 'ceo', + ), + action: 'buy', + reason: 'Human execution.', + }); + + expect(ceo.allowed).toBe(true); + }); + + test('duplicate request ids are idempotent', async () => { + const { engine } = + await createResearchWorkflow(); + + const first = + await engine.transition({ + requestId: 'same-request', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Begin research.', + }); + + const second = + await engine.transition({ + requestId: 'same-request', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Duplicate request.', + }); + + expect(first.duplicate).toBe(false); + expect(second.duplicate).toBe(true); + expect( + second.workflow.revision, + ).toBe(first.workflow.revision); + }); + + test('optimistic concurrency rejects stale revisions', async () => { + const { engine } = + await createResearchWorkflow(); + + await engine.transition({ + requestId: 'first', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Begin.', + }); + + await expect( + engine.registerArtifact({ + requestId: 'stale', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + expectedRevision: 0, + artifact: { + id: 'artifact-stale', + workflowId: 'wf-1', + kind: 'research_proposal', + createdBy: { + kind: 'agent', + id: 'lauti', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + summary: 'Proposal.', + metadata: {}, + }, + reason: 'Stale write.', + }), + ).rejects.toThrow( + 'workflow_revision_conflict', + ); + }); + + test('control plane creates auditable workflow history', async () => { + const { engine } = + await createResearchWorkflow(); + + await engine.transition({ + requestId: 'transition-audit', + workflowId: 'wf-1', + principal: actor( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Begin research.', + }); + + const audit = + await engine.listAudit('wf-1'); + + expect(audit.length).toBeGreaterThan(1); + + expect( + audit.some( + (record) => + record.action === + 'workflow.transition' && + record.outcome === + 'transitioned', + ), + ).toBe(true); + }); +}); diff --git a/tests/control-plane-jobs.test.ts b/tests/control-plane-jobs.test.ts new file mode 100644 index 00000000..8dd06850 --- /dev/null +++ b/tests/control-plane-jobs.test.ts @@ -0,0 +1,83 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + canRetryJob, + computeRetryDelayMs, + isJobTimedOut, + nextRetryAt, + type ScheduledJob, +} from '@/lib/control-plane/jobs'; + +const policy = { + maxAttempts: 4, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 5_000, + timeoutMs: 10_000, +}; + +describe('Control Plane scheduling helpers', () => { + test('calculates bounded exponential retry delay', () => { + expect( + computeRetryDelayMs(policy, 1), + ).toBe(1_000); + + expect( + computeRetryDelayMs(policy, 2), + ).toBe(2_000); + + expect( + computeRetryDelayMs(policy, 4), + ).toBe(5_000); + }); + + test('detects timeout without inventing business risk limits', () => { + const job: ScheduledJob = { + id: 'job-1', + kind: 'monitoring-check', + runAt: + '2026-01-01T00:00:00.000Z', + status: 'running', + attempts: 1, + startedAt: + '2026-01-01T00:00:00.000Z', + retryPolicy: policy, + metadata: {}, + }; + + expect( + isJobTimedOut( + job, + '2026-01-01T00:00:11.000Z', + ), + ).toBe(true); + }); + + test('allows retries only within technical retry policy', () => { + const job: ScheduledJob = { + id: 'job-2', + kind: 'retry-example', + runAt: + '2026-01-01T00:00:00.000Z', + status: 'failed', + attempts: 2, + retryPolicy: policy, + metadata: {}, + }; + + expect(canRetryJob(job)).toBe(true); + + expect( + nextRetryAt( + job, + '2026-01-01T00:00:00.000Z', + ), + ).toBe( + '2026-01-01T00:00:02.000Z', + ); + }); +}); diff --git a/tests/control-plane-state-machine.test.ts b/tests/control-plane-state-machine.test.ts new file mode 100644 index 00000000..bbdf8170 --- /dev/null +++ b/tests/control-plane-state-machine.test.ts @@ -0,0 +1,64 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import { + canTransitionState, +} from '@/lib/control-plane/state-machine'; + +import { + INVESTMENT_WORKFLOW_TRANSITIONS, + NUMERIC_RISK_LIMITS_DEFINED, +} from '@/lib/control-plane/spec'; + +describe('Company Control Plane state machine', () => { + test('matches canonical investment workflow transitions', () => { + expect( + INVESTMENT_WORKFLOW_TRANSITIONS.DRAFT, + ).toEqual(['RESEARCHING']); + + expect( + INVESTMENT_WORKFLOW_TRANSITIONS + .WAITING_CEO_RESEARCH_DECISION, + ).toEqual([ + 'CEO_RESEARCH_REJECTED', + 'CEO_RESEARCH_APPROVED', + ]); + + expect( + INVESTMENT_WORKFLOW_TRANSITIONS.RISK_REVIEW, + ).toEqual([ + 'RISK_REJECTED', + 'RISK_MODIFICATION_REQUIRED', + 'RISK_APPROVED', + ]); + + expect( + INVESTMENT_WORKFLOW_TRANSITIONS.ARCHIVED, + ).toEqual([]); + }); + + test('rejects skipped workflow transitions', () => { + expect( + canTransitionState( + 'DRAFT', + 'RISK_APPROVED', + ), + ).toBe(false); + + expect( + canTransitionState( + 'WAITING_CEO_EXECUTION', + 'MONITORING', + ), + ).toBe(false); + }); + + test('does not invent numerical risk limits', () => { + expect( + NUMERIC_RISK_LIMITS_DEFINED, + ).toBe(false); + }); +}); From 3ebb51ad0ece05b65f7190de69d6be4cc40bb08a Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 19:10:51 +0200 Subject: [PATCH 45/62] Add durable control plane persistence foundation --- lib/control-plane/durable-schema.ts | 162 +++ lib/control-plane/durable.ts | 83 ++ lib/control-plane/index.ts | 3 + lib/control-plane/sqlite-store.ts | 1193 ++++++++++++++++++++++ tests/control-plane-durable-jobs.test.ts | 181 ++++ tests/control-plane-outbox.test.ts | 185 ++++ tests/control-plane-sqlite-store.test.ts | 260 +++++ 7 files changed, 2067 insertions(+) create mode 100644 lib/control-plane/durable-schema.ts create mode 100644 lib/control-plane/durable.ts create mode 100644 lib/control-plane/sqlite-store.ts create mode 100644 tests/control-plane-durable-jobs.test.ts create mode 100644 tests/control-plane-outbox.test.ts create mode 100644 tests/control-plane-sqlite-store.test.ts diff --git a/lib/control-plane/durable-schema.ts b/lib/control-plane/durable-schema.ts new file mode 100644 index 00000000..d25f464f --- /dev/null +++ b/lib/control-plane/durable-schema.ts @@ -0,0 +1,162 @@ +import { z } from 'zod'; + +import { + BrainActorSchema, + TimestampSchema, +} from '@/lib/brain/core-schema'; + +import { + RetryPolicySchema, +} from '@/lib/control-plane/jobs'; + +export const ControlPlaneCommandTypeSchema = z.enum([ + 'create_workflow', + 'register_artifact', + 'transition_workflow', + 'record_invalidation', + 'resolve_invalidation', + 'authorize_financial_action', + 'schedule_job', + 'cancel_job', +]); + +export const ControlPlaneCommandOutcomeSchema = z.enum([ + 'accepted', + 'succeeded', + 'denied', + 'duplicate', + 'failed', +]); + +export const ControlPlaneCommandRecordSchema = z.object({ + commandId: z.string().min(1), + requestId: z.string().min(1), + workflowId: z.string().min(1).optional(), + commandType: ControlPlaneCommandTypeSchema, + actor: BrainActorSchema, + receivedAt: TimestampSchema, + outcome: ControlPlaneCommandOutcomeSchema, + reason: z.string().default(''), + payload: z.record(z.unknown()).default({}), +}); + +export const ControlPlaneDomainEventTypeSchema = z.enum([ + 'workflow_created', + 'artifact_registered', + 'workflow_transitioned', + 'invalidation_recorded', + 'invalidation_resolved', + 'financial_action_authorized', + 'financial_action_denied', + 'job_scheduled', + 'job_completed', + 'job_failed', +]); + +export const ControlPlaneDomainEventSchema = z.object({ + eventId: z.string().min(1), + requestId: z.string().min(1), + workflowId: z.string().min(1).optional(), + sequence: z.number().int().min(0).optional(), + eventType: ControlPlaneDomainEventTypeSchema, + actor: BrainActorSchema, + occurredAt: TimestampSchema, + payload: z.record(z.unknown()).default({}), +}); + +export const OutboxStatusSchema = z.enum([ + 'pending', + 'in_flight', + 'published', + 'dead_letter', +]); + +export const ControlPlaneOutboxMessageSchema = z.object({ + messageId: z.string().min(1), + topic: z.string().min(1), + partitionKey: z.string().min(1), + workflowId: z.string().min(1).optional(), + + status: OutboxStatusSchema.default('pending'), + attempts: z.number().int().min(0).default(0), + + createdAt: TimestampSchema, + availableAt: TimestampSchema, + + retryPolicy: RetryPolicySchema, + + leaseOwner: z.string().min(1).optional(), + leaseUntil: TimestampSchema.optional(), + + lastError: z.string().optional(), + publishedAt: TimestampSchema.optional(), + + payload: z.record(z.unknown()).default({}), +}); + +export const DurableJobStatusSchema = z.enum([ + 'scheduled', + 'running', + 'succeeded', + 'cancelled', + 'dead_letter', +]); + +export const DurableScheduledJobSchema = z.object({ + jobId: z.string().min(1), + workflowId: z.string().min(1).optional(), + kind: z.string().min(1), + + status: DurableJobStatusSchema.default('scheduled'), + attempts: z.number().int().min(0).default(0), + + runAt: TimestampSchema, + createdAt: TimestampSchema, + + startedAt: TimestampSchema.optional(), + completedAt: TimestampSchema.optional(), + + retryPolicy: RetryPolicySchema, + + leaseOwner: z.string().min(1).optional(), + leaseUntil: TimestampSchema.optional(), + + lastError: z.string().optional(), + + payload: z.record(z.unknown()).default({}), +}); + +export const ClaimBatchSchema = z.object({ + workerId: z.string().min(1), + now: TimestampSchema, + limit: z.number().int().positive().max(500), + leaseMs: z.number().int().positive().max(60 * 60 * 1000), +}); + +export type ControlPlaneCommandRecord = z.infer< + typeof ControlPlaneCommandRecordSchema +>; + +export type ControlPlaneDomainEvent = z.infer< + typeof ControlPlaneDomainEventSchema +>; + +export type ControlPlaneOutboxMessage = z.infer< + typeof ControlPlaneOutboxMessageSchema +>; + +export type ControlPlaneOutboxMessageInput = z.input< + typeof ControlPlaneOutboxMessageSchema +>; + +export type DurableScheduledJobInput = z.input< + typeof DurableScheduledJobSchema +>; + +export type DurableScheduledJob = z.infer< + typeof DurableScheduledJobSchema +>; + +export type ClaimBatchInput = z.input< + typeof ClaimBatchSchema +>; diff --git a/lib/control-plane/durable.ts b/lib/control-plane/durable.ts new file mode 100644 index 00000000..9d69bedd --- /dev/null +++ b/lib/control-plane/durable.ts @@ -0,0 +1,83 @@ +import type { + ControlPlaneCommandRecord, + ControlPlaneDomainEvent, + ControlPlaneOutboxMessage, + DurableScheduledJob, + ClaimBatchInput, + ControlPlaneOutboxMessageInput, + DurableScheduledJobInput, +} from '@/lib/control-plane/durable-schema'; + +export interface ControlPlaneCommandLedger { + appendCommand( + record: ControlPlaneCommandRecord, + ): void; + + listCommands( + workflowId?: string, + ): ControlPlaneCommandRecord[]; +} + +export interface ControlPlaneDomainEventLedger { + appendDomainEvent( + event: ControlPlaneDomainEvent, + ): void; + + listDomainEvents( + workflowId?: string, + ): ControlPlaneDomainEvent[]; +} + +export interface ControlPlaneOutboxStore { + enqueueOutbox( + message: ControlPlaneOutboxMessageInput, + ): void; + + listOutbox(): ControlPlaneOutboxMessage[]; + + claimOutbox( + input: ClaimBatchInput, + ): ControlPlaneOutboxMessage[]; + + acknowledgeOutbox(input: { + messageId: string; + workerId: string; + publishedAt: string; + }): void; + + failOutbox(input: { + messageId: string; + workerId: string; + failedAt: string; + error: string; + }): ControlPlaneOutboxMessage; +} + +export interface ControlPlaneJobStore { + scheduleJob( + job: DurableScheduledJobInput, + ): void; + + listJobs(): DurableScheduledJob[]; + + claimDueJobs( + input: ClaimBatchInput, + ): DurableScheduledJob[]; + + completeJob(input: { + jobId: string; + workerId: string; + completedAt: string; + }): void; + + failJob(input: { + jobId: string; + workerId: string; + failedAt: string; + error: string; + }): DurableScheduledJob; + + cancelJob(input: { + jobId: string; + }): void; +} diff --git a/lib/control-plane/index.ts b/lib/control-plane/index.ts index ad3e169e..7391a6c4 100644 --- a/lib/control-plane/index.ts +++ b/lib/control-plane/index.ts @@ -7,3 +7,6 @@ export * from '@/lib/control-plane/store'; export * from '@/lib/control-plane/jobs'; export * from '@/lib/control-plane/brain-bridge'; export * from '@/lib/control-plane/engine'; +export * from '@/lib/control-plane/durable-schema'; +export * from '@/lib/control-plane/durable'; +export * from '@/lib/control-plane/sqlite-store'; \ No newline at end of file diff --git a/lib/control-plane/sqlite-store.ts b/lib/control-plane/sqlite-store.ts new file mode 100644 index 00000000..02fc71db --- /dev/null +++ b/lib/control-plane/sqlite-store.ts @@ -0,0 +1,1193 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +import Database from 'better-sqlite3'; + +import { + ControlPlaneAuditRecordSchema, + InvestmentWorkflowSchema, + type ControlPlaneAuditRecord, + type InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +import { + ClaimBatchSchema, + ControlPlaneCommandRecordSchema, + ControlPlaneDomainEventSchema, + ControlPlaneOutboxMessageSchema, + DurableScheduledJobSchema, + type ClaimBatchInput, + type ControlPlaneCommandRecord, + type ControlPlaneDomainEvent, + type ControlPlaneOutboxMessage, + type DurableScheduledJob, + type ControlPlaneOutboxMessageInput, + type DurableScheduledJobInput, +} from '@/lib/control-plane/durable-schema'; + +import { + computeRetryDelayMs, +} from '@/lib/control-plane/jobs'; + +import type { + ControlPlaneStore, +} from '@/lib/control-plane/store'; + +const DDL = ` +CREATE TABLE IF NOT EXISTS cp_workflows ( + id TEXT PRIMARY KEY, + revision INTEGER NOT NULL, + state TEXT NOT NULL, + snapshot_json TEXT NOT NULL, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +); + +CREATE TABLE IF NOT EXISTS cp_processed_requests ( + request_id TEXT PRIMARY KEY, + processed_at TEXT NOT NULL +); + +CREATE TABLE IF NOT EXISTS cp_audit ( + audit_id TEXT PRIMARY KEY, + request_id TEXT NOT NULL, + workflow_id TEXT, + at TEXT NOT NULL, + action TEXT NOT NULL, + outcome TEXT NOT NULL, + record_json TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS cp_audit_workflow_at_idx +ON cp_audit(workflow_id, at); + +CREATE TABLE IF NOT EXISTS cp_commands ( + command_id TEXT PRIMARY KEY, + request_id TEXT NOT NULL UNIQUE, + workflow_id TEXT, + command_type TEXT NOT NULL, + actor_json TEXT NOT NULL, + received_at TEXT NOT NULL, + outcome TEXT NOT NULL, + reason TEXT NOT NULL, + payload_json TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS cp_commands_workflow_received_idx +ON cp_commands(workflow_id, received_at); + +CREATE TABLE IF NOT EXISTS cp_domain_events ( + event_id TEXT PRIMARY KEY, + request_id TEXT NOT NULL, + workflow_id TEXT, + sequence INTEGER, + event_type TEXT NOT NULL, + actor_json TEXT NOT NULL, + occurred_at TEXT NOT NULL, + payload_json TEXT NOT NULL, + UNIQUE(workflow_id, sequence) +); + +CREATE INDEX IF NOT EXISTS cp_domain_events_workflow_sequence_idx +ON cp_domain_events(workflow_id, sequence); + +CREATE TABLE IF NOT EXISTS cp_outbox ( + message_id TEXT PRIMARY KEY, + topic TEXT NOT NULL, + partition_key TEXT NOT NULL, + workflow_id TEXT, + status TEXT NOT NULL, + attempts INTEGER NOT NULL, + created_at TEXT NOT NULL, + available_at TEXT NOT NULL, + retry_policy_json TEXT NOT NULL, + lease_owner TEXT, + lease_until TEXT, + last_error TEXT, + published_at TEXT, + payload_json TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS cp_outbox_delivery_idx +ON cp_outbox(status, available_at, lease_until); + +CREATE TABLE IF NOT EXISTS cp_jobs ( + job_id TEXT PRIMARY KEY, + workflow_id TEXT, + kind TEXT NOT NULL, + status TEXT NOT NULL, + attempts INTEGER NOT NULL, + run_at TEXT NOT NULL, + created_at TEXT NOT NULL, + started_at TEXT, + completed_at TEXT, + retry_policy_json TEXT NOT NULL, + lease_owner TEXT, + lease_until TEXT, + last_error TEXT, + payload_json TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS cp_jobs_due_idx +ON cp_jobs(status, run_at, lease_until); +`; + +function ensureParentDirectory( + dbPath: string, +): void { + if (dbPath === ':memory:') { + return; + } + + fs.mkdirSync( + path.dirname(dbPath), + { recursive: true }, + ); +} + +function parseJson( + value: string, +): T { + return JSON.parse(value) as T; +} + +function addMs( + iso: string, + milliseconds: number, +): string { + return new Date( + Date.parse(iso) + milliseconds, + ).toISOString(); +} + +type WorkflowRow = { + snapshot_json: string; +}; + +type AuditRow = { + record_json: string; +}; + +type CommandRow = { + command_id: string; + request_id: string; + workflow_id: string | null; + command_type: string; + actor_json: string; + received_at: string; + outcome: string; + reason: string; + payload_json: string; +}; + +type DomainEventRow = { + event_id: string; + request_id: string; + workflow_id: string | null; + sequence: number | null; + event_type: string; + actor_json: string; + occurred_at: string; + payload_json: string; +}; + +type OutboxRow = { + message_id: string; + topic: string; + partition_key: string; + workflow_id: string | null; + status: string; + attempts: number; + created_at: string; + available_at: string; + retry_policy_json: string; + lease_owner: string | null; + lease_until: string | null; + last_error: string | null; + published_at: string | null; + payload_json: string; +}; + +type JobRow = { + job_id: string; + workflow_id: string | null; + kind: string; + status: string; + attempts: number; + run_at: string; + created_at: string; + started_at: string | null; + completed_at: string | null; + retry_policy_json: string; + lease_owner: string | null; + lease_until: string | null; + last_error: string | null; + payload_json: string; +}; + +function rowToCommand( + row: CommandRow, +): ControlPlaneCommandRecord { + return ControlPlaneCommandRecordSchema.parse({ + commandId: row.command_id, + requestId: row.request_id, + workflowId: row.workflow_id ?? undefined, + commandType: row.command_type, + actor: parseJson(row.actor_json), + receivedAt: row.received_at, + outcome: row.outcome, + reason: row.reason, + payload: parseJson(row.payload_json), + }); +} + +function rowToDomainEvent( + row: DomainEventRow, +): ControlPlaneDomainEvent { + return ControlPlaneDomainEventSchema.parse({ + eventId: row.event_id, + requestId: row.request_id, + workflowId: row.workflow_id ?? undefined, + sequence: row.sequence ?? undefined, + eventType: row.event_type, + actor: parseJson(row.actor_json), + occurredAt: row.occurred_at, + payload: parseJson(row.payload_json), + }); +} + +function rowToOutbox( + row: OutboxRow, +): ControlPlaneOutboxMessage { + return ControlPlaneOutboxMessageSchema.parse({ + messageId: row.message_id, + topic: row.topic, + partitionKey: row.partition_key, + workflowId: row.workflow_id ?? undefined, + status: row.status, + attempts: row.attempts, + createdAt: row.created_at, + availableAt: row.available_at, + retryPolicy: parseJson(row.retry_policy_json), + leaseOwner: row.lease_owner ?? undefined, + leaseUntil: row.lease_until ?? undefined, + lastError: row.last_error ?? undefined, + publishedAt: row.published_at ?? undefined, + payload: parseJson(row.payload_json), + }); +} + +function rowToJob( + row: JobRow, +): DurableScheduledJob { + return DurableScheduledJobSchema.parse({ + jobId: row.job_id, + workflowId: row.workflow_id ?? undefined, + kind: row.kind, + status: row.status, + attempts: row.attempts, + runAt: row.run_at, + createdAt: row.created_at, + startedAt: row.started_at ?? undefined, + completedAt: row.completed_at ?? undefined, + retryPolicy: parseJson(row.retry_policy_json), + leaseOwner: row.lease_owner ?? undefined, + leaseUntil: row.lease_until ?? undefined, + lastError: row.last_error ?? undefined, + payload: parseJson(row.payload_json), + }); +} + +export class SqliteControlPlaneStore + implements ControlPlaneStore +{ + private readonly db: InstanceType< + typeof Database + >; + + constructor(dbPath: string) { + ensureParentDirectory(dbPath); + + this.db = new Database(dbPath); + + this.db.pragma('journal_mode = WAL'); + this.db.pragma('foreign_keys = ON'); + this.db.pragma('busy_timeout = 5000'); + + this.db.exec(DDL); + } + + close(): void { + this.db.close(); + } + + async getWorkflow( + workflowId: string, + ): Promise { + const row = this.db + .prepare( + 'SELECT snapshot_json FROM cp_workflows WHERE id = ?', + ) + .get(workflowId) as + | WorkflowRow + | undefined; + + if (!row) { + return null; + } + + return InvestmentWorkflowSchema.parse( + parseJson(row.snapshot_json), + ); + } + + async createWorkflow( + workflowInput: InvestmentWorkflow, + ): Promise { + const workflow = + InvestmentWorkflowSchema.parse( + workflowInput, + ); + + try { + this.db + .prepare( + `INSERT INTO cp_workflows + (id, revision, state, snapshot_json, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + ) + .run( + workflow.id, + workflow.revision, + workflow.state, + JSON.stringify(workflow), + workflow.createdAt, + workflow.updatedAt, + ); + } catch (error) { + if ( + error instanceof Error && + error.message.includes( + 'UNIQUE constraint failed', + ) + ) { + throw new Error( + `workflow_already_exists:${workflow.id}`, + ); + } + + throw error; + } + + return structuredClone(workflow); + } + + async replaceWorkflow(input: { + workflow: InvestmentWorkflow; + expectedRevision: number; + }): Promise { + const workflow = + InvestmentWorkflowSchema.parse( + input.workflow, + ); + + const result = this.db + .prepare( + `UPDATE cp_workflows + SET revision = ?, + state = ?, + snapshot_json = ?, + updated_at = ? + WHERE id = ? + AND revision = ?`, + ) + .run( + workflow.revision, + workflow.state, + JSON.stringify(workflow), + workflow.updatedAt, + workflow.id, + input.expectedRevision, + ); + + if (result.changes === 1) { + return structuredClone(workflow); + } + + const current = this.db + .prepare( + 'SELECT revision FROM cp_workflows WHERE id = ?', + ) + .get(workflow.id) as + | { revision: number } + | undefined; + + if (!current) { + throw new Error( + `workflow_not_found:${workflow.id}`, + ); + } + + throw new Error( + `workflow_revision_conflict:expected=${input.expectedRevision}:actual=${current.revision}`, + ); + } + + async hasProcessedRequest( + requestId: string, + ): Promise { + const row = this.db + .prepare( + 'SELECT 1 AS found FROM cp_processed_requests WHERE request_id = ?', + ) + .get(requestId) as + | { found: number } + | undefined; + + return row?.found === 1; + } + + async markProcessedRequest( + requestId: string, + ): Promise { + this.db + .prepare( + `INSERT OR IGNORE INTO cp_processed_requests + (request_id, processed_at) + VALUES (?, ?)`, + ) + .run( + requestId, + new Date().toISOString(), + ); + } + + async appendAudit( + recordInput: ControlPlaneAuditRecord, + ): Promise { + const record = + ControlPlaneAuditRecordSchema.parse( + recordInput, + ); + + this.db + .prepare( + `INSERT INTO cp_audit + (audit_id, request_id, workflow_id, at, action, outcome, record_json) + VALUES (?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + record.auditId, + record.requestId, + record.workflowId ?? null, + record.at, + record.action, + record.outcome, + JSON.stringify(record), + ); + } + + async listAudit( + workflowId?: string, + ): Promise { + const rows = workflowId + ? (this.db + .prepare( + `SELECT record_json + FROM cp_audit + WHERE workflow_id = ? + ORDER BY at, rowid`, + ) + .all(workflowId) as AuditRow[]) + : (this.db + .prepare( + `SELECT record_json + FROM cp_audit + ORDER BY at, rowid`, + ) + .all() as AuditRow[]); + + return rows.map((row) => + ControlPlaneAuditRecordSchema.parse( + parseJson(row.record_json), + ), + ); + } + + appendCommand( + recordInput: ControlPlaneCommandRecord, + ): void { + const record = + ControlPlaneCommandRecordSchema.parse( + recordInput, + ); + + this.db + .prepare( + `INSERT INTO cp_commands + ( + command_id, + request_id, + workflow_id, + command_type, + actor_json, + received_at, + outcome, + reason, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + record.commandId, + record.requestId, + record.workflowId ?? null, + record.commandType, + JSON.stringify(record.actor), + record.receivedAt, + record.outcome, + record.reason, + JSON.stringify(record.payload), + ); + } + + listCommands( + workflowId?: string, + ): ControlPlaneCommandRecord[] { + const rows = workflowId + ? (this.db + .prepare( + `SELECT * + FROM cp_commands + WHERE workflow_id = ? + ORDER BY received_at, rowid`, + ) + .all(workflowId) as CommandRow[]) + : (this.db + .prepare( + `SELECT * + FROM cp_commands + ORDER BY received_at, rowid`, + ) + .all() as CommandRow[]); + + return rows.map(rowToCommand); + } + + appendDomainEvent( + eventInput: ControlPlaneDomainEvent, + ): void { + const event = + ControlPlaneDomainEventSchema.parse( + eventInput, + ); + + this.db + .prepare( + `INSERT INTO cp_domain_events + ( + event_id, + request_id, + workflow_id, + sequence, + event_type, + actor_json, + occurred_at, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + event.eventId, + event.requestId, + event.workflowId ?? null, + event.sequence ?? null, + event.eventType, + JSON.stringify(event.actor), + event.occurredAt, + JSON.stringify(event.payload), + ); + } + + listDomainEvents( + workflowId?: string, + ): ControlPlaneDomainEvent[] { + const rows = workflowId + ? (this.db + .prepare( + `SELECT * + FROM cp_domain_events + WHERE workflow_id = ? + ORDER BY sequence, occurred_at, rowid`, + ) + .all(workflowId) as DomainEventRow[]) + : (this.db + .prepare( + `SELECT * + FROM cp_domain_events + ORDER BY occurred_at, rowid`, + ) + .all() as DomainEventRow[]); + + return rows.map(rowToDomainEvent); + } + + enqueueOutbox( + messageInput: ControlPlaneOutboxMessageInput, + ): void { + const message = + ControlPlaneOutboxMessageSchema.parse( + messageInput, + ); + + this.db + .prepare( + `INSERT INTO cp_outbox + ( + message_id, + topic, + partition_key, + workflow_id, + status, + attempts, + created_at, + available_at, + retry_policy_json, + lease_owner, + lease_until, + last_error, + published_at, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + message.messageId, + message.topic, + message.partitionKey, + message.workflowId ?? null, + message.status, + message.attempts, + message.createdAt, + message.availableAt, + JSON.stringify(message.retryPolicy), + message.leaseOwner ?? null, + message.leaseUntil ?? null, + message.lastError ?? null, + message.publishedAt ?? null, + JSON.stringify(message.payload), + ); + } + + listOutbox(): ControlPlaneOutboxMessage[] { + const rows = this.db + .prepare( + `SELECT * + FROM cp_outbox + ORDER BY created_at, rowid`, + ) + .all() as OutboxRow[]; + + return rows.map(rowToOutbox); + } + + claimOutbox( + inputRaw: ClaimBatchInput, + ): ControlPlaneOutboxMessage[] { + const input = + ClaimBatchSchema.parse(inputRaw); + + const leaseUntil = addMs( + input.now, + input.leaseMs, + ); + + const transaction = + this.db.transaction(() => { + const candidates = this.db + .prepare( + `SELECT message_id + FROM cp_outbox + WHERE available_at <= ? + AND ( + status = 'pending' + OR ( + status = 'in_flight' + AND lease_until IS NOT NULL + AND lease_until <= ? + ) + ) + ORDER BY available_at, created_at, rowid + LIMIT ?`, + ) + .all( + input.now, + input.now, + input.limit, + ) as Array<{ + message_id: string; + }>; + + const claimed: ControlPlaneOutboxMessage[] = + []; + + const claim = this.db.prepare( + `UPDATE cp_outbox + SET status = 'in_flight', + attempts = attempts + 1, + lease_owner = ?, + lease_until = ? + WHERE message_id = ? + AND ( + status = 'pending' + OR ( + status = 'in_flight' + AND lease_until IS NOT NULL + AND lease_until <= ? + ) + )`, + ); + + const read = this.db.prepare( + `SELECT * + FROM cp_outbox + WHERE message_id = ?`, + ); + + for (const candidate of candidates) { + const result = claim.run( + input.workerId, + leaseUntil, + candidate.message_id, + input.now, + ); + + if (result.changes !== 1) { + continue; + } + + const row = read.get( + candidate.message_id, + ) as OutboxRow; + + claimed.push( + rowToOutbox(row), + ); + } + + return claimed; + }); + + return transaction(); + } + + acknowledgeOutbox(input: { + messageId: string; + workerId: string; + publishedAt: string; + }): void { + const result = this.db + .prepare( + `UPDATE cp_outbox + SET status = 'published', + published_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = NULL + WHERE message_id = ? + AND status = 'in_flight' + AND lease_owner = ?`, + ) + .run( + input.publishedAt, + input.messageId, + input.workerId, + ); + + if (result.changes !== 1) { + throw new Error( + `outbox_ack_lease_mismatch:${input.messageId}`, + ); + } + } + + failOutbox(input: { + messageId: string; + workerId: string; + failedAt: string; + error: string; + }): ControlPlaneOutboxMessage { + const transaction = + this.db.transaction(() => { + const row = this.db + .prepare( + `SELECT * + FROM cp_outbox + WHERE message_id = ?`, + ) + .get(input.messageId) as + | OutboxRow + | undefined; + + if (!row) { + throw new Error( + `outbox_message_not_found:${input.messageId}`, + ); + } + + const current = + rowToOutbox(row); + + if ( + current.status !== 'in_flight' || + current.leaseOwner !== + input.workerId + ) { + throw new Error( + `outbox_fail_lease_mismatch:${input.messageId}`, + ); + } + + const exhausted = + current.attempts >= + current.retryPolicy.maxAttempts; + + const delayMs = + computeRetryDelayMs( + current.retryPolicy, + current.attempts, + ); + + const nextAvailableAt = addMs( + input.failedAt, + delayMs, + ); + + this.db + .prepare( + `UPDATE cp_outbox + SET status = ?, + available_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = ? + WHERE message_id = ?`, + ) + .run( + exhausted + ? 'dead_letter' + : 'pending', + exhausted + ? current.availableAt + : nextAvailableAt, + input.error, + input.messageId, + ); + + const updated = this.db + .prepare( + `SELECT * + FROM cp_outbox + WHERE message_id = ?`, + ) + .get( + input.messageId, + ) as OutboxRow; + + return rowToOutbox(updated); + }); + + return transaction(); + } + + scheduleJob( + jobInput: DurableScheduledJobInput, + ): void { + const job = + DurableScheduledJobSchema.parse( + jobInput, + ); + + this.db + .prepare( + `INSERT INTO cp_jobs + ( + job_id, + workflow_id, + kind, + status, + attempts, + run_at, + created_at, + started_at, + completed_at, + retry_policy_json, + lease_owner, + lease_until, + last_error, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + job.jobId, + job.workflowId ?? null, + job.kind, + job.status, + job.attempts, + job.runAt, + job.createdAt, + job.startedAt ?? null, + job.completedAt ?? null, + JSON.stringify(job.retryPolicy), + job.leaseOwner ?? null, + job.leaseUntil ?? null, + job.lastError ?? null, + JSON.stringify(job.payload), + ); + } + + listJobs(): DurableScheduledJob[] { + const rows = this.db + .prepare( + `SELECT * + FROM cp_jobs + ORDER BY run_at, rowid`, + ) + .all() as JobRow[]; + + return rows.map(rowToJob); + } + + claimDueJobs( + inputRaw: ClaimBatchInput, + ): DurableScheduledJob[] { + const input = + ClaimBatchSchema.parse(inputRaw); + + const leaseUntil = addMs( + input.now, + input.leaseMs, + ); + + const transaction = + this.db.transaction(() => { + const candidates = this.db + .prepare( + `SELECT job_id + FROM cp_jobs + WHERE run_at <= ? + AND ( + status = 'scheduled' + OR ( + status = 'running' + AND lease_until IS NOT NULL + AND lease_until <= ? + ) + ) + ORDER BY run_at, created_at, rowid + LIMIT ?`, + ) + .all( + input.now, + input.now, + input.limit, + ) as Array<{ + job_id: string; + }>; + + const claim = this.db.prepare( + `UPDATE cp_jobs + SET status = 'running', + attempts = attempts + 1, + started_at = ?, + lease_owner = ?, + lease_until = ? + WHERE job_id = ? + AND ( + status = 'scheduled' + OR ( + status = 'running' + AND lease_until IS NOT NULL + AND lease_until <= ? + ) + )`, + ); + + const read = this.db.prepare( + `SELECT * + FROM cp_jobs + WHERE job_id = ?`, + ); + + const claimed: DurableScheduledJob[] = + []; + + for (const candidate of candidates) { + const result = claim.run( + input.now, + input.workerId, + leaseUntil, + candidate.job_id, + input.now, + ); + + if (result.changes !== 1) { + continue; + } + + claimed.push( + rowToJob( + read.get( + candidate.job_id, + ) as JobRow, + ), + ); + } + + return claimed; + }); + + return transaction(); + } + + completeJob(input: { + jobId: string; + workerId: string; + completedAt: string; + }): void { + const result = this.db + .prepare( + `UPDATE cp_jobs + SET status = 'succeeded', + completed_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = NULL + WHERE job_id = ? + AND status = 'running' + AND lease_owner = ?`, + ) + .run( + input.completedAt, + input.jobId, + input.workerId, + ); + + if (result.changes !== 1) { + throw new Error( + `job_complete_lease_mismatch:${input.jobId}`, + ); + } + } + + failJob(input: { + jobId: string; + workerId: string; + failedAt: string; + error: string; + }): DurableScheduledJob { + const transaction = + this.db.transaction(() => { + const row = this.db + .prepare( + `SELECT * + FROM cp_jobs + WHERE job_id = ?`, + ) + .get(input.jobId) as + | JobRow + | undefined; + + if (!row) { + throw new Error( + `job_not_found:${input.jobId}`, + ); + } + + const current = + rowToJob(row); + + if ( + current.status !== 'running' || + current.leaseOwner !== + input.workerId + ) { + throw new Error( + `job_fail_lease_mismatch:${input.jobId}`, + ); + } + + const exhausted = + current.attempts >= + current.retryPolicy.maxAttempts; + + const delayMs = + computeRetryDelayMs( + current.retryPolicy, + current.attempts, + ); + + const nextRunAt = addMs( + input.failedAt, + delayMs, + ); + + this.db + .prepare( + `UPDATE cp_jobs + SET status = ?, + run_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = ? + WHERE job_id = ?`, + ) + .run( + exhausted + ? 'dead_letter' + : 'scheduled', + exhausted + ? current.runAt + : nextRunAt, + input.error, + input.jobId, + ); + + return rowToJob( + this.db + .prepare( + `SELECT * + FROM cp_jobs + WHERE job_id = ?`, + ) + .get( + input.jobId, + ) as JobRow, + ); + }); + + return transaction(); + } + + cancelJob(input: { + jobId: string; + }): void { + const result = this.db + .prepare( + `UPDATE cp_jobs + SET status = 'cancelled', + lease_owner = NULL, + lease_until = NULL + WHERE job_id = ? + AND status IN ('scheduled', 'running')`, + ) + .run(input.jobId); + + if (result.changes !== 1) { + throw new Error( + `job_not_cancellable:${input.jobId}`, + ); + } + } +} diff --git a/tests/control-plane-durable-jobs.test.ts b/tests/control-plane-durable-jobs.test.ts new file mode 100644 index 00000000..6e22e6c1 --- /dev/null +++ b/tests/control-plane-durable-jobs.test.ts @@ -0,0 +1,181 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + SqliteControlPlaneStore, +} from '@/lib/control-plane/sqlite-store'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function store() { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-jobs-', + ), + ); + + return new SqliteControlPlaneStore( + path.join( + tempDir, + 'cp.db', + ), + ); +} + +const retryPolicy = { + maxAttempts: 2, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, +}; + +describe('Control Plane durable jobs', () => { + test('claims a due job with a lease and prevents concurrent claim', () => { + const cp = store(); + + cp.scheduleJob({ + jobId: 'job-1', + workflowId: 'wf-1', + kind: + 'monitor_position', + runAt: + '2026-01-01T00:00:00.000Z', + createdAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: {}, + }); + + const a = + cp.claimDueJobs({ + workerId: 'worker-a', + now: + '2026-01-01T00:00:01.000Z', + limit: 10, + leaseMs: 60_000, + }); + + const b = + cp.claimDueJobs({ + workerId: 'worker-b', + now: + '2026-01-01T00:00:02.000Z', + limit: 10, + leaseMs: 60_000, + }); + + expect(a).toHaveLength(1); + expect(b).toHaveLength(0); + + cp.completeJob({ + jobId: 'job-1', + workerId: 'worker-a', + completedAt: + '2026-01-01T00:00:03.000Z', + }); + + expect( + cp.listJobs()[0], + ).toMatchObject({ + status: 'succeeded', + attempts: 1, + }); + + cp.close(); + }); + + test('retries failed durable jobs and dead-letters exhausted jobs', () => { + const cp = store(); + + cp.scheduleJob({ + jobId: 'job-2', + kind: + 'refresh-material-event', + runAt: + '2026-01-01T00:00:00.000Z', + createdAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: {}, + }); + + cp.claimDueJobs({ + workerId: 'worker-a', + now: + '2026-01-01T00:00:01.000Z', + limit: 1, + leaseMs: 10_000, + }); + + const retry = + cp.failJob({ + jobId: 'job-2', + workerId: 'worker-a', + failedAt: + '2026-01-01T00:00:02.000Z', + error: 'temporary', + }); + + expect(retry.status).toBe( + 'scheduled', + ); + + expect(retry.runAt).toBe( + '2026-01-01T00:00:03.000Z', + ); + + cp.claimDueJobs({ + workerId: 'worker-b', + now: + '2026-01-01T00:00:03.000Z', + limit: 1, + leaseMs: 10_000, + }); + + const dead = + cp.failJob({ + jobId: 'job-2', + workerId: 'worker-b', + failedAt: + '2026-01-01T00:00:04.000Z', + error: 'permanent', + }); + + expect(dead.status).toBe( + 'dead_letter', + ); + + cp.close(); + }); +}); diff --git a/tests/control-plane-outbox.test.ts b/tests/control-plane-outbox.test.ts new file mode 100644 index 00000000..54b39beb --- /dev/null +++ b/tests/control-plane-outbox.test.ts @@ -0,0 +1,185 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + SqliteControlPlaneStore, +} from '@/lib/control-plane/sqlite-store'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function store() { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-outbox-', + ), + ); + + return new SqliteControlPlaneStore( + path.join( + tempDir, + 'cp.db', + ), + ); +} + +const retryPolicy = { + maxAttempts: 2, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, +}; + +describe('Control Plane durable outbox', () => { + test('leases messages to one worker and publishes them exactly once at store level', () => { + const cp = store(); + + cp.enqueueOutbox({ + messageId: 'msg-1', + topic: + 'workflow.transitioned', + partitionKey: 'wf-1', + workflowId: 'wf-1', + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: { + state: 'RESEARCHING', + }, + }); + + const workerA = + cp.claimOutbox({ + workerId: 'worker-a', + now: + '2026-01-01T00:00:01.000Z', + limit: 10, + leaseMs: 60_000, + }); + + const workerB = + cp.claimOutbox({ + workerId: 'worker-b', + now: + '2026-01-01T00:00:02.000Z', + limit: 10, + leaseMs: 60_000, + }); + + expect(workerA).toHaveLength(1); + expect(workerB).toHaveLength(0); + + cp.acknowledgeOutbox({ + messageId: 'msg-1', + workerId: 'worker-a', + publishedAt: + '2026-01-01T00:00:03.000Z', + }); + + expect( + cp.listOutbox()[0], + ).toMatchObject({ + status: 'published', + attempts: 1, + }); + + cp.close(); + }); + + test('retries failures then moves exhausted message to dead letter', () => { + const cp = store(); + + cp.enqueueOutbox({ + messageId: 'msg-2', + topic: + 'brain.memory.proposed', + partitionKey: 'wf-2', + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: {}, + }); + + cp.claimOutbox({ + workerId: 'worker-a', + now: + '2026-01-01T00:00:01.000Z', + limit: 1, + leaseMs: 10_000, + }); + + const retry = + cp.failOutbox({ + messageId: 'msg-2', + workerId: 'worker-a', + failedAt: + '2026-01-01T00:00:02.000Z', + error: 'temporary', + }); + + expect(retry.status).toBe( + 'pending', + ); + + expect(retry.availableAt).toBe( + '2026-01-01T00:00:03.000Z', + ); + + cp.claimOutbox({ + workerId: 'worker-b', + now: + '2026-01-01T00:00:03.000Z', + limit: 1, + leaseMs: 10_000, + }); + + const dead = + cp.failOutbox({ + messageId: 'msg-2', + workerId: 'worker-b', + failedAt: + '2026-01-01T00:00:04.000Z', + error: 'permanent', + }); + + expect(dead.status).toBe( + 'dead_letter', + ); + + cp.close(); + }); +}); diff --git a/tests/control-plane-sqlite-store.test.ts b/tests/control-plane-sqlite-store.test.ts new file mode 100644 index 00000000..48d8fc76 --- /dev/null +++ b/tests/control-plane-sqlite-store.test.ts @@ -0,0 +1,260 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + SqliteControlPlaneStore, +} from '@/lib/control-plane/sqlite-store'; + +import type { + InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function databasePath(): string { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-cp-v2-', + ), + ); + + return path.join( + tempDir, + 'control-plane.db', + ); +} + +function workflow( + revision = 0, +): InvestmentWorkflow { + return { + id: 'wf-1', + state: + revision === 0 + ? 'DRAFT' + : 'RESEARCHING', + revision, + createdBy: { + kind: 'agent', + id: 'lauti', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + updatedAt: + revision === 0 + ? '2026-01-01T00:00:00.000Z' + : '2026-01-01T00:01:00.000Z', + responsibleResearchAgentId: + 'lauti', + assetRef: 'asset:test', + artifacts: [], + invalidations: [], + metadata: {}, + }; +} + +describe('SQLite Control Plane persistence', () => { + test('survives process-store reopen for workflow, idempotency and audit', async () => { + const dbPath = databasePath(); + + const first = + new SqliteControlPlaneStore( + dbPath, + ); + + await first.createWorkflow( + workflow(), + ); + + await first.markProcessedRequest( + 'request-1', + ); + + await first.appendAudit({ + auditId: 'audit-1', + requestId: 'request-1', + at: + '2026-01-01T00:00:00.000Z', + actor: { + kind: 'agent', + id: 'lauti', + }, + action: 'workflow.create', + outcome: 'created', + reason: 'test', + workflowId: 'wf-1', + workflowRevisionAfter: 0, + metadata: {}, + }); + + first.close(); + + const second = + new SqliteControlPlaneStore( + dbPath, + ); + + expect( + await second.getWorkflow('wf-1'), + ).toMatchObject({ + id: 'wf-1', + revision: 0, + state: 'DRAFT', + }); + + expect( + await second.hasProcessedRequest( + 'request-1', + ), + ).toBe(true); + + expect( + await second.listAudit('wf-1'), + ).toHaveLength(1); + + second.close(); + }); + + test('enforces optimistic concurrency across independent store instances', async () => { + const dbPath = databasePath(); + + const storeA = + new SqliteControlPlaneStore( + dbPath, + ); + + const storeB = + new SqliteControlPlaneStore( + dbPath, + ); + + await storeA.createWorkflow( + workflow(), + ); + + await storeA.replaceWorkflow({ + workflow: workflow(1), + expectedRevision: 0, + }); + + await expect( + storeB.replaceWorkflow({ + workflow: { + ...workflow(1), + updatedAt: + '2026-01-01T00:02:00.000Z', + }, + expectedRevision: 0, + }), + ).rejects.toThrow( + 'workflow_revision_conflict', + ); + + storeA.close(); + storeB.close(); + }); + + test('persists append-only command and domain-event ledgers', () => { + const store = + new SqliteControlPlaneStore( + databasePath(), + ); + + store.appendCommand({ + commandId: 'cmd-1', + requestId: 'request-1', + workflowId: 'wf-1', + commandType: + 'transition_workflow', + actor: { + kind: 'agent', + id: 'lauti', + }, + receivedAt: + '2026-01-01T00:00:00.000Z', + outcome: 'succeeded', + reason: 'test', + payload: { + from: 'DRAFT', + to: 'RESEARCHING', + }, + }); + + store.appendDomainEvent({ + eventId: 'evt-1', + requestId: 'request-1', + workflowId: 'wf-1', + sequence: 1, + eventType: + 'workflow_transitioned', + actor: { + kind: 'agent', + id: 'lauti', + }, + occurredAt: + '2026-01-01T00:00:00.000Z', + payload: { + from: 'DRAFT', + to: 'RESEARCHING', + }, + }); + + expect( + store.listCommands('wf-1'), + ).toHaveLength(1); + + expect( + store.listDomainEvents('wf-1'), + ).toHaveLength(1); + + expect(() => + store.appendDomainEvent({ + eventId: 'evt-2', + requestId: 'request-2', + workflowId: 'wf-1', + sequence: 1, + eventType: + 'workflow_transitioned', + actor: { + kind: 'agent', + id: 'lauti', + }, + occurredAt: + '2026-01-01T00:01:00.000Z', + payload: {}, + }), + ).toThrow(); + + store.close(); + }); +}); From 920beab9fccd529662a83cdb677cf7a42416f642 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 19:24:22 +0200 Subject: [PATCH 46/62] Add atomic control plane unit of work --- lib/control-plane/atomic-engine.ts | 1111 ++++++++++++++++++++++ lib/control-plane/atomic-store.ts | 81 ++ lib/control-plane/index.ts | 5 +- lib/control-plane/sqlite-atomic-store.ts | 444 +++++++++ lib/control-plane/sqlite-store.ts | 2 +- tests/control-plane-atomic-uow.test.ts | 382 ++++++++ 6 files changed, 2023 insertions(+), 2 deletions(-) create mode 100644 lib/control-plane/atomic-engine.ts create mode 100644 lib/control-plane/atomic-store.ts create mode 100644 lib/control-plane/sqlite-atomic-store.ts create mode 100644 tests/control-plane-atomic-uow.test.ts diff --git a/lib/control-plane/atomic-engine.ts b/lib/control-plane/atomic-engine.ts new file mode 100644 index 00000000..48b494c1 --- /dev/null +++ b/lib/control-plane/atomic-engine.ts @@ -0,0 +1,1111 @@ +import { + CreateWorkflowRequestSchema, + FinancialActionRequestSchema, + InvestmentWorkflowSchema, + RecordInvalidationRequestSchema, + RegisterArtifactRequestSchema, + ResolveInvalidationRequestSchema, + TransitionRequestSchema, + type AuthorizationDecision, + type ControlPlaneAuditRecord, + type ControlPlanePrincipal, + type InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +import type { + AtomicControlPlaneCommitInput, + AtomicControlPlaneStore, +} from '@/lib/control-plane/atomic-store'; + +import { + canAuthorizeFinancialAction, + canCreateInvestmentWorkflow, + canRecordMaterialInvalidation, + canRegisterArtifact, + canRequestTransition, + canResolveMaterialInvalidation, +} from '@/lib/control-plane/permissions'; + +import { + assertStateTransitionShape, +} from '@/lib/control-plane/state-machine'; + +import { + evaluateWorkflowGates, +} from '@/lib/control-plane/gates'; + +import { + IMMUTABLE_HISTORICAL_ARTIFACTS, +} from '@/lib/control-plane/spec'; + +const DEFAULT_OUTBOX_RETRY_POLICY = { + maxAttempts: 5, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 60_000, + timeoutMs: 30_000, +} as const; + +function combineDecisions( + ...decisions: AuthorizationDecision[] +): AuthorizationDecision { + const missingRequirements = + decisions.flatMap( + (decision) => + decision.missingRequirements, + ); + + const denied = decisions.find( + (decision) => !decision.allowed, + ); + + return denied + ? { + allowed: false, + reason: denied.reason, + missingRequirements, + } + : { + allowed: true, + reason: 'all_control_plane_checks_passed', + missingRequirements: [], + }; +} + +export class AtomicCompanyControlPlane { + constructor( + private readonly store: AtomicControlPlaneStore, + private readonly clock: () => string = () => + new Date().toISOString(), + ) {} + + private auditId( + requestId: string, + suffix: string, + ): string { + return `cp-audit:${requestId}:${suffix}`; + } + + private commandId( + requestId: string, + ): string { + return `cp-command:${requestId}`; + } + + private eventId( + requestId: string, + ): string { + return `cp-event:${requestId}`; + } + + private outboxId( + requestId: string, + ): string { + return `cp-outbox:${requestId}`; + } + + private async auditDenied( + record: Omit< + ControlPlaneAuditRecord, + 'at' + > & { + at?: string; + }, + ): Promise { + await this.store.appendAudit({ + ...record, + at: record.at ?? this.clock(), + }); + } + + private async requireWorkflow( + workflowId: string, + ): Promise { + const workflow = + await this.store.getWorkflow( + workflowId, + ); + + if (!workflow) { + throw new Error( + `workflow_not_found:${workflowId}`, + ); + } + + return workflow; + } + + private assertExpectedRevision( + workflow: InvestmentWorkflow, + expectedRevision?: number, + ): void { + if ( + expectedRevision !== undefined && + workflow.revision !== + expectedRevision + ) { + throw new Error( + `workflow_revision_conflict:expected=${expectedRevision}:actual=${workflow.revision}`, + ); + } + } + + private async duplicateWorkflowResult( + requestId: string, + workflowId: string, + ) { + const command = + await this.store.getCommandByRequestId( + requestId, + ); + + if (!command) { + return null; + } + + const workflow = + await this.requireWorkflow(workflowId); + + return { + workflow, + duplicate: true as const, + }; + } + + private buildAtomicCommit(input: { + requestId: string; + workflowId?: string; + commandType: + | 'create_workflow' + | 'register_artifact' + | 'transition_workflow' + | 'record_invalidation' + | 'resolve_invalidation' + | 'authorize_financial_action'; + principal: ControlPlanePrincipal; + reason: string; + commandPayload: Record; + mutation: AtomicControlPlaneCommitInput['mutation']; + audit: ControlPlaneAuditRecord; + eventType: + | 'workflow_created' + | 'artifact_registered' + | 'workflow_transitioned' + | 'invalidation_recorded' + | 'invalidation_resolved' + | 'financial_action_authorized' + | 'financial_action_denied'; + eventPayload: Record; + sequence?: number; + outboxTopic: string; + commandOutcome?: 'succeeded' | 'denied'; + at: string; + }): AtomicControlPlaneCommitInput { + const eventId = + this.eventId(input.requestId); + + return { + command: { + commandId: + this.commandId(input.requestId), + requestId: input.requestId, + workflowId: input.workflowId, + commandType: input.commandType, + actor: input.principal.actor, + receivedAt: input.at, + outcome: + input.commandOutcome ?? 'succeeded', + reason: input.reason, + payload: input.commandPayload, + }, + mutation: input.mutation, + processedAt: input.at, + audit: input.audit, + events: [ + { + eventId, + requestId: input.requestId, + workflowId: input.workflowId, + sequence: input.sequence, + eventType: input.eventType, + actor: input.principal.actor, + occurredAt: input.at, + payload: input.eventPayload, + }, + ], + outbox: [ + { + messageId: + this.outboxId(input.requestId), + topic: input.outboxTopic, + partitionKey: + input.workflowId ?? + input.requestId, + workflowId: input.workflowId, + createdAt: input.at, + availableAt: input.at, + retryPolicy: + DEFAULT_OUTBOX_RETRY_POLICY, + payload: { + eventId, + eventType: input.eventType, + ...input.eventPayload, + }, + }, + ], + }; + } + + async createWorkflow( + input: Parameters< + typeof CreateWorkflowRequestSchema.parse + >[0], + ) { + const request = + CreateWorkflowRequestSchema.parse(input); + + const duplicate = + await this.duplicateWorkflowResult( + request.requestId, + request.workflowId, + ); + + if (duplicate) { + return duplicate; + } + + const permission = + canCreateInvestmentWorkflow( + request.principal, + request.responsibleResearchAgentId, + ); + + if (!permission.allowed) { + await this.auditDenied({ + auditId: this.auditId( + request.requestId, + 'denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.create', + outcome: 'denied', + reason: permission.reason, + workflowId: request.workflowId, + metadata: {}, + }); + + throw new Error(permission.reason); + } + + const now = this.clock(); + + const workflow = + InvestmentWorkflowSchema.parse({ + id: request.workflowId, + state: 'DRAFT', + revision: 0, + createdBy: + request.principal.actor, + createdAt: now, + updatedAt: now, + responsibleResearchAgentId: + request.responsibleResearchAgentId, + assetRef: request.assetRef, + artifacts: [], + invalidations: [], + metadata: request.metadata, + }); + + const result = + await this.store.commitAtomic( + this.buildAtomicCommit({ + requestId: request.requestId, + workflowId: workflow.id, + commandType: 'create_workflow', + principal: request.principal, + reason: request.reason, + commandPayload: { + responsibleResearchAgentId: + request.responsibleResearchAgentId, + assetRef: request.assetRef, + }, + mutation: { + kind: 'create', + workflow, + }, + audit: { + auditId: this.auditId( + request.requestId, + 'created', + ), + requestId: request.requestId, + at: now, + actor: request.principal.actor, + action: 'workflow.create', + outcome: 'created', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionAfter: 0, + metadata: { + state: workflow.state, + persistence: + 'atomic_unit_of_work', + }, + }, + eventType: 'workflow_created', + eventPayload: { + state: workflow.state, + }, + sequence: 0, + outboxTopic: + 'control-plane.workflow.created', + at: now, + }), + ); + + if (!result.workflow) { + throw new Error( + 'atomic_create_missing_workflow', + ); + } + + return { + workflow: result.workflow, + duplicate: result.duplicate, + }; + } + + async registerArtifact( + input: Parameters< + typeof RegisterArtifactRequestSchema.parse + >[0], + ) { + const request = + RegisterArtifactRequestSchema.parse( + input, + ); + + const duplicate = + await this.duplicateWorkflowResult( + request.requestId, + request.workflowId, + ); + + if (duplicate) { + return duplicate; + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + if ( + request.artifact.workflowId !== + workflow.id + ) { + throw new Error( + 'artifact_workflow_id_mismatch', + ); + } + + if ( + request.artifact.createdBy.id !== + request.principal.actor.id || + request.artifact.createdBy.kind !== + request.principal.actor.kind + ) { + throw new Error( + 'artifact_creator_must_match_request_principal', + ); + } + + const permission = + canRegisterArtifact( + request.principal, + request.artifact.kind, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + if ( + workflow.artifacts.some( + (artifact) => + artifact.id === + request.artifact.id, + ) + ) { + throw new Error( + `artifact_id_already_exists:${request.artifact.id}`, + ); + } + + const before = workflow.revision; + const now = this.clock(); + + workflow = + InvestmentWorkflowSchema.parse({ + ...workflow, + revision: before + 1, + updatedAt: now, + artifacts: [ + ...workflow.artifacts, + request.artifact, + ], + }); + + const result = + await this.store.commitAtomic( + this.buildAtomicCommit({ + requestId: request.requestId, + workflowId: workflow.id, + commandType: 'register_artifact', + principal: request.principal, + reason: request.reason, + commandPayload: { + artifactId: + request.artifact.id, + artifactKind: + request.artifact.kind, + }, + mutation: { + kind: 'replace', + workflow, + expectedRevision: before, + }, + audit: { + auditId: this.auditId( + request.requestId, + 'artifact', + ), + requestId: request.requestId, + at: now, + actor: request.principal.actor, + action: + 'workflow.register_artifact', + outcome: 'recorded', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + artifactId: + request.artifact.id, + artifactKind: + request.artifact.kind, + immutableHistoricalRecord: + IMMUTABLE_HISTORICAL_ARTIFACTS.has( + request.artifact.kind, + ), + persistence: + 'atomic_unit_of_work', + }, + }, + eventType: 'artifact_registered', + eventPayload: { + artifactId: + request.artifact.id, + artifactKind: + request.artifact.kind, + }, + sequence: workflow.revision, + outboxTopic: + 'control-plane.artifact.registered', + at: now, + }), + ); + + if (!result.workflow) { + throw new Error( + 'atomic_artifact_missing_workflow', + ); + } + + return { + workflow: result.workflow, + duplicate: result.duplicate, + }; + } + + async transition( + input: Parameters< + typeof TransitionRequestSchema.parse + >[0], + ) { + const request = + TransitionRequestSchema.parse(input); + + const duplicate = + await this.duplicateWorkflowResult( + request.requestId, + request.workflowId, + ); + + if (duplicate) { + return duplicate; + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + const decision = combineDecisions( + assertStateTransitionShape( + workflow, + request.fromState, + request.toState, + ), + canRequestTransition( + request.principal, + request.fromState, + ), + evaluateWorkflowGates( + workflow, + request.fromState, + request.toState, + ), + ); + + if (!decision.allowed) { + await this.auditDenied({ + auditId: this.auditId( + request.requestId, + 'transition-denied', + ), + requestId: request.requestId, + actor: request.principal.actor, + action: 'workflow.transition', + outcome: 'denied', + reason: decision.reason, + workflowId: workflow.id, + workflowRevisionBefore: + workflow.revision, + workflowRevisionAfter: + workflow.revision, + metadata: { + fromState: request.fromState, + toState: request.toState, + missingRequirements: + decision.missingRequirements, + }, + }); + + throw new Error( + [ + decision.reason, + ...decision.missingRequirements, + ].join('|'), + ); + } + + const before = workflow.revision; + const now = this.clock(); + + workflow = + InvestmentWorkflowSchema.parse({ + ...workflow, + state: request.toState, + revision: before + 1, + updatedAt: now, + }); + + const result = + await this.store.commitAtomic( + this.buildAtomicCommit({ + requestId: request.requestId, + workflowId: workflow.id, + commandType: 'transition_workflow', + principal: request.principal, + reason: request.reason, + commandPayload: { + fromState: request.fromState, + toState: request.toState, + }, + mutation: { + kind: 'replace', + workflow, + expectedRevision: before, + }, + audit: { + auditId: this.auditId( + request.requestId, + 'transitioned', + ), + requestId: request.requestId, + at: now, + actor: request.principal.actor, + action: 'workflow.transition', + outcome: 'transitioned', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + fromState: request.fromState, + toState: request.toState, + transitionAuthority: + 'control_plane_only', + persistence: + 'atomic_unit_of_work', + }, + }, + eventType: + 'workflow_transitioned', + eventPayload: { + fromState: request.fromState, + toState: request.toState, + }, + sequence: workflow.revision, + outboxTopic: + 'control-plane.workflow.transitioned', + at: now, + }), + ); + + if (!result.workflow) { + throw new Error( + 'atomic_transition_missing_workflow', + ); + } + + return { + workflow: result.workflow, + duplicate: result.duplicate, + }; + } + + async recordInvalidation( + input: Parameters< + typeof RecordInvalidationRequestSchema.parse + >[0], + ) { + const request = + RecordInvalidationRequestSchema.parse( + input, + ); + + const duplicate = + await this.duplicateWorkflowResult( + request.requestId, + request.workflowId, + ); + + if (duplicate) { + return duplicate; + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + const permission = + canRecordMaterialInvalidation( + request.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + if ( + request.invalidation.workflowId !== + workflow.id + ) { + throw new Error( + 'invalidation_workflow_id_mismatch', + ); + } + + if ( + request.invalidation.recordedBy.id !== + request.principal.actor.id || + request.invalidation.recordedBy.kind !== + request.principal.actor.kind + ) { + throw new Error( + 'invalidation_recorder_must_match_request_principal', + ); + } + + if ( + workflow.invalidations.some( + (item) => + item.id === + request.invalidation.id, + ) + ) { + throw new Error( + `invalidation_id_already_exists:${request.invalidation.id}`, + ); + } + + const before = workflow.revision; + const now = this.clock(); + + workflow = + InvestmentWorkflowSchema.parse({ + ...workflow, + revision: before + 1, + updatedAt: now, + invalidations: [ + ...workflow.invalidations, + request.invalidation, + ], + }); + + const result = + await this.store.commitAtomic( + this.buildAtomicCommit({ + requestId: request.requestId, + workflowId: workflow.id, + commandType: + 'record_invalidation', + principal: request.principal, + reason: request.reason, + commandPayload: { + invalidationId: + request.invalidation.id, + invalidationKind: + request.invalidation.kind, + }, + mutation: { + kind: 'replace', + workflow, + expectedRevision: before, + }, + audit: { + auditId: this.auditId( + request.requestId, + 'invalidation', + ), + requestId: request.requestId, + at: now, + actor: request.principal.actor, + action: + 'workflow.record_invalidation', + outcome: 'recorded', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + invalidationId: + request.invalidation.id, + invalidationKind: + request.invalidation.kind, + persistence: + 'atomic_unit_of_work', + }, + }, + eventType: + 'invalidation_recorded', + eventPayload: { + invalidationId: + request.invalidation.id, + invalidationKind: + request.invalidation.kind, + }, + sequence: workflow.revision, + outboxTopic: + 'control-plane.invalidation.recorded', + at: now, + }), + ); + + if (!result.workflow) { + throw new Error( + 'atomic_invalidation_missing_workflow', + ); + } + + return { + workflow: result.workflow, + duplicate: result.duplicate, + }; + } + + async resolveInvalidation( + input: Parameters< + typeof ResolveInvalidationRequestSchema.parse + >[0], + ) { + const request = + ResolveInvalidationRequestSchema.parse( + input, + ); + + const duplicate = + await this.duplicateWorkflowResult( + request.requestId, + request.workflowId, + ); + + if (duplicate) { + return duplicate; + } + + let workflow = + await this.requireWorkflow( + request.workflowId, + ); + + this.assertExpectedRevision( + workflow, + request.expectedRevision, + ); + + const permission = + canResolveMaterialInvalidation( + request.principal, + ); + + if (!permission.allowed) { + throw new Error(permission.reason); + } + + const target = + workflow.invalidations.find( + (item) => + item.id === + request.invalidationId, + ); + + if (!target) { + throw new Error( + `invalidation_not_found:${request.invalidationId}`, + ); + } + + if (target.status === 'resolved') { + throw new Error( + `invalidation_already_resolved:${request.invalidationId}`, + ); + } + + const before = workflow.revision; + const now = this.clock(); + + workflow = + InvestmentWorkflowSchema.parse({ + ...workflow, + revision: before + 1, + updatedAt: now, + invalidations: + workflow.invalidations.map( + (item) => + item.id === + request.invalidationId + ? { + ...item, + status: + 'resolved' as const, + resolvedBy: + request.principal.actor, + resolvedAt: now, + resolutionReason: + request.reason, + } + : item, + ), + }); + + const result = + await this.store.commitAtomic( + this.buildAtomicCommit({ + requestId: request.requestId, + workflowId: workflow.id, + commandType: + 'resolve_invalidation', + principal: request.principal, + reason: request.reason, + commandPayload: { + invalidationId: + request.invalidationId, + }, + mutation: { + kind: 'replace', + workflow, + expectedRevision: before, + }, + audit: { + auditId: this.auditId( + request.requestId, + 'invalidation-resolved', + ), + requestId: request.requestId, + at: now, + actor: request.principal.actor, + action: + 'workflow.resolve_invalidation', + outcome: 'recorded', + reason: request.reason, + workflowId: workflow.id, + workflowRevisionBefore: before, + workflowRevisionAfter: + workflow.revision, + metadata: { + invalidationId: + request.invalidationId, + persistence: + 'atomic_unit_of_work', + }, + }, + eventType: + 'invalidation_resolved', + eventPayload: { + invalidationId: + request.invalidationId, + }, + sequence: workflow.revision, + outboxTopic: + 'control-plane.invalidation.resolved', + at: now, + }), + ); + + if (!result.workflow) { + throw new Error( + 'atomic_resolution_missing_workflow', + ); + } + + return { + workflow: result.workflow, + duplicate: result.duplicate, + }; + } + + async authorizeFinancialAction( + input: Parameters< + typeof FinancialActionRequestSchema.parse + >[0], + ) { + const request = + FinancialActionRequestSchema.parse( + input, + ); + + const existing = + await this.store.getCommandByRequestId( + request.requestId, + ); + + if (existing) { + return { + allowed: + existing.outcome === 'succeeded', + reason: existing.reason, + missingRequirements: [], + }; + } + + const permission = + canAuthorizeFinancialAction( + request.principal, + request.action, + ); + + const now = this.clock(); + const eventType = permission.allowed + ? 'financial_action_authorized' as const + : 'financial_action_denied' as const; + + await this.store.commitAtomic( + this.buildAtomicCommit({ + requestId: request.requestId, + workflowId: request.workflowId, + commandType: + 'authorize_financial_action', + principal: request.principal, + reason: permission.reason, + commandPayload: { + financialAction: + request.action, + requestedReason: + request.reason, + }, + mutation: { + kind: 'none', + }, + audit: { + auditId: this.auditId( + request.requestId, + permission.allowed + ? 'financial-authorized' + : 'financial-denied', + ), + requestId: request.requestId, + at: now, + actor: request.principal.actor, + action: + `financial.${request.action}`, + outcome: permission.allowed + ? 'authorized' + : 'denied', + reason: permission.reason, + workflowId: request.workflowId, + metadata: { + financialAction: + request.action, + persistence: + 'atomic_unit_of_work', + }, + }, + eventType, + eventPayload: { + financialAction: + request.action, + allowed: permission.allowed, + }, + outboxTopic: permission.allowed + ? 'control-plane.financial-action.authorized' + : 'control-plane.financial-action.denied', + commandOutcome: permission.allowed + ? 'succeeded' + : 'denied', + at: now, + }), + ); + + return permission; + } + + async getWorkflow( + workflowId: string, + ) { + return this.requireWorkflow( + workflowId, + ); + } + + async listAudit( + workflowId?: string, + ) { + return this.store.listAudit( + workflowId, + ); + } +} diff --git a/lib/control-plane/atomic-store.ts b/lib/control-plane/atomic-store.ts new file mode 100644 index 00000000..0ea0cd1f --- /dev/null +++ b/lib/control-plane/atomic-store.ts @@ -0,0 +1,81 @@ +import { z } from 'zod'; + +import { + TimestampSchema, +} from '@/lib/brain/core-schema'; + +import { + ControlPlaneAuditRecordSchema, + InvestmentWorkflowSchema, + type InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +import { + ControlPlaneCommandRecordSchema, + ControlPlaneDomainEventSchema, + ControlPlaneOutboxMessageSchema, + type ControlPlaneCommandRecord, +} from '@/lib/control-plane/durable-schema'; + +import type { + ControlPlaneStore, +} from '@/lib/control-plane/store'; + +export const AtomicWorkflowMutationSchema = + z.discriminatedUnion('kind', [ + z.object({ + kind: z.literal('none'), + }), + z.object({ + kind: z.literal('create'), + workflow: InvestmentWorkflowSchema, + }), + z.object({ + kind: z.literal('replace'), + workflow: InvestmentWorkflowSchema, + expectedRevision: z.number().int().min(0), + }), + ]); + +export const AtomicControlPlaneCommitSchema = z.object({ + command: ControlPlaneCommandRecordSchema, + mutation: AtomicWorkflowMutationSchema, + processedAt: TimestampSchema, + audit: ControlPlaneAuditRecordSchema, + events: z + .array(ControlPlaneDomainEventSchema) + .min(1), + outbox: z + .array(ControlPlaneOutboxMessageSchema) + .min(1), +}); + +export type AtomicWorkflowMutation = z.infer< + typeof AtomicWorkflowMutationSchema +>; + +export type AtomicControlPlaneCommitInput = z.input< + typeof AtomicControlPlaneCommitSchema +>; + +export type AtomicControlPlaneCommit = z.infer< + typeof AtomicControlPlaneCommitSchema +>; + +export type AtomicControlPlaneCommitResult = { + duplicate: boolean; + workflow?: InvestmentWorkflow; + command?: ControlPlaneCommandRecord; +}; + +export interface AtomicControlPlaneStore + extends ControlPlaneStore +{ + getCommandByRequestId( + requestId: string, + ): Promise; + + commitAtomic( + input: AtomicControlPlaneCommitInput, + ): Promise; +} diff --git a/lib/control-plane/index.ts b/lib/control-plane/index.ts index 7391a6c4..d99bf120 100644 --- a/lib/control-plane/index.ts +++ b/lib/control-plane/index.ts @@ -9,4 +9,7 @@ export * from '@/lib/control-plane/brain-bridge'; export * from '@/lib/control-plane/engine'; export * from '@/lib/control-plane/durable-schema'; export * from '@/lib/control-plane/durable'; -export * from '@/lib/control-plane/sqlite-store'; \ No newline at end of file +export * from '@/lib/control-plane/sqlite-store'; +export * from '@/lib/control-plane/atomic-store'; +export * from '@/lib/control-plane/sqlite-atomic-store'; +export * from '@/lib/control-plane/atomic-engine'; \ No newline at end of file diff --git a/lib/control-plane/sqlite-atomic-store.ts b/lib/control-plane/sqlite-atomic-store.ts new file mode 100644 index 00000000..2e7e3df8 --- /dev/null +++ b/lib/control-plane/sqlite-atomic-store.ts @@ -0,0 +1,444 @@ +import { + AtomicControlPlaneCommitSchema, + type AtomicControlPlaneCommitInput, + type AtomicControlPlaneCommitResult, + type AtomicControlPlaneStore, +} from '@/lib/control-plane/atomic-store'; + +import { + InvestmentWorkflowSchema, + type InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +import { + ControlPlaneCommandRecordSchema, + type ControlPlaneCommandRecord, +} from '@/lib/control-plane/durable-schema'; + +import { + SqliteControlPlaneStore, +} from '@/lib/control-plane/sqlite-store'; + +type CommandRow = { + command_id: string; + request_id: string; + workflow_id: string | null; + command_type: string; + actor_json: string; + received_at: string; + outcome: string; + reason: string; + payload_json: string; +}; + +type WorkflowRow = { + snapshot_json: string; +}; + +function parseJson( + value: string, +): T { + return JSON.parse(value) as T; +} + +function rowToCommand( + row: CommandRow, +): ControlPlaneCommandRecord { + return ControlPlaneCommandRecordSchema.parse({ + commandId: row.command_id, + requestId: row.request_id, + workflowId: row.workflow_id ?? undefined, + commandType: row.command_type, + actor: parseJson(row.actor_json), + receivedAt: row.received_at, + outcome: row.outcome, + reason: row.reason, + payload: parseJson(row.payload_json), + }); +} + +export class SqliteAtomicControlPlaneStore + extends SqliteControlPlaneStore + implements AtomicControlPlaneStore +{ + async getCommandByRequestId( + requestId: string, + ): Promise { + const row = this.db + .prepare( + `SELECT * + FROM cp_commands + WHERE request_id = ?`, + ) + .get(requestId) as + | CommandRow + | undefined; + + return row + ? rowToCommand(row) + : null; + } + + async commitAtomic( + inputRaw: AtomicControlPlaneCommitInput, + ): Promise { + const input = + AtomicControlPlaneCommitSchema.parse( + inputRaw, + ); + + const transaction = + this.db.transaction(() => { + const existingCommand = this.db + .prepare( + `SELECT * + FROM cp_commands + WHERE request_id = ?`, + ) + .get( + input.command.requestId, + ) as + | CommandRow + | undefined; + + if (existingCommand) { + const command = + rowToCommand(existingCommand); + + const workflow = + command.workflowId + ? this.readWorkflowSync( + command.workflowId, + ) + : undefined; + + return { + duplicate: true, + workflow, + command, + }; + } + + const legacyProcessed = this.db + .prepare( + `SELECT 1 AS found + FROM cp_processed_requests + WHERE request_id = ?`, + ) + .get( + input.command.requestId, + ) as + | { found: number } + | undefined; + + if (legacyProcessed?.found === 1) { + const workflow = + input.command.workflowId + ? this.readWorkflowSync( + input.command.workflowId, + ) + : undefined; + + return { + duplicate: true, + workflow, + }; + } + + this.insertCommand(input.command); + + let workflow: + | InvestmentWorkflow + | undefined; + + if (input.mutation.kind === 'create') { + workflow = + this.createWorkflowSync( + input.mutation.workflow, + ); + } else if ( + input.mutation.kind === 'replace' + ) { + workflow = + this.replaceWorkflowSync({ + workflow: + input.mutation.workflow, + expectedRevision: + input.mutation.expectedRevision, + }); + } else if ( + input.command.workflowId + ) { + workflow = this.readWorkflowSync( + input.command.workflowId, + ); + } + + this.db + .prepare( + `INSERT INTO cp_processed_requests + (request_id, processed_at) + VALUES (?, ?)`, + ) + .run( + input.command.requestId, + input.processedAt, + ); + + this.db + .prepare( + `INSERT INTO cp_audit + ( + audit_id, + request_id, + workflow_id, + at, + action, + outcome, + record_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + input.audit.auditId, + input.audit.requestId, + input.audit.workflowId ?? null, + input.audit.at, + input.audit.action, + input.audit.outcome, + JSON.stringify(input.audit), + ); + + for (const event of input.events) { + this.db + .prepare( + `INSERT INTO cp_domain_events + ( + event_id, + request_id, + workflow_id, + sequence, + event_type, + actor_json, + occurred_at, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + event.eventId, + event.requestId, + event.workflowId ?? null, + event.sequence ?? null, + event.eventType, + JSON.stringify(event.actor), + event.occurredAt, + JSON.stringify(event.payload), + ); + } + + for (const message of input.outbox) { + this.db + .prepare( + `INSERT INTO cp_outbox + ( + message_id, + topic, + partition_key, + workflow_id, + status, + attempts, + created_at, + available_at, + retry_policy_json, + lease_owner, + lease_until, + last_error, + published_at, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + message.messageId, + message.topic, + message.partitionKey, + message.workflowId ?? null, + message.status, + message.attempts, + message.createdAt, + message.availableAt, + JSON.stringify( + message.retryPolicy, + ), + message.leaseOwner ?? null, + message.leaseUntil ?? null, + message.lastError ?? null, + message.publishedAt ?? null, + JSON.stringify(message.payload), + ); + } + + return { + duplicate: false, + workflow, + command: input.command, + }; + }); + + return transaction(); + } + + private readWorkflowSync( + workflowId: string, + ): InvestmentWorkflow | undefined { + const row = this.db + .prepare( + `SELECT snapshot_json + FROM cp_workflows + WHERE id = ?`, + ) + .get(workflowId) as + | WorkflowRow + | undefined; + + return row + ? InvestmentWorkflowSchema.parse( + parseJson(row.snapshot_json), + ) + : undefined; + } + + private createWorkflowSync( + workflowInput: InvestmentWorkflow, + ): InvestmentWorkflow { + const workflow = + InvestmentWorkflowSchema.parse( + workflowInput, + ); + + try { + this.db + .prepare( + `INSERT INTO cp_workflows + ( + id, + revision, + state, + snapshot_json, + created_at, + updated_at + ) + VALUES (?, ?, ?, ?, ?, ?)`, + ) + .run( + workflow.id, + workflow.revision, + workflow.state, + JSON.stringify(workflow), + workflow.createdAt, + workflow.updatedAt, + ); + } catch (error) { + if ( + error instanceof Error && + error.message.includes( + 'UNIQUE constraint failed', + ) + ) { + throw new Error( + `workflow_already_exists:${workflow.id}`, + ); + } + + throw error; + } + + return workflow; + } + + private replaceWorkflowSync(input: { + workflow: InvestmentWorkflow; + expectedRevision: number; + }): InvestmentWorkflow { + const workflow = + InvestmentWorkflowSchema.parse( + input.workflow, + ); + + const result = this.db + .prepare( + `UPDATE cp_workflows + SET revision = ?, + state = ?, + snapshot_json = ?, + updated_at = ? + WHERE id = ? + AND revision = ?`, + ) + .run( + workflow.revision, + workflow.state, + JSON.stringify(workflow), + workflow.updatedAt, + workflow.id, + input.expectedRevision, + ); + + if (result.changes === 1) { + return workflow; + } + + const current = this.db + .prepare( + `SELECT revision + FROM cp_workflows + WHERE id = ?`, + ) + .get(workflow.id) as + | { revision: number } + | undefined; + + if (!current) { + throw new Error( + `workflow_not_found:${workflow.id}`, + ); + } + + throw new Error( + `workflow_revision_conflict:expected=${input.expectedRevision}:actual=${current.revision}`, + ); + } + + private insertCommand( + command: ControlPlaneCommandRecord, + ): void { + this.db + .prepare( + `INSERT INTO cp_commands + ( + command_id, + request_id, + workflow_id, + command_type, + actor_json, + received_at, + outcome, + reason, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .run( + command.commandId, + command.requestId, + command.workflowId ?? null, + command.commandType, + JSON.stringify(command.actor), + command.receivedAt, + command.outcome, + command.reason, + JSON.stringify(command.payload), + ); + } +} diff --git a/lib/control-plane/sqlite-store.ts b/lib/control-plane/sqlite-store.ts index 02fc71db..274a062c 100644 --- a/lib/control-plane/sqlite-store.ts +++ b/lib/control-plane/sqlite-store.ts @@ -301,7 +301,7 @@ function rowToJob( export class SqliteControlPlaneStore implements ControlPlaneStore { - private readonly db: InstanceType< + protected readonly db: InstanceType< typeof Database >; diff --git a/tests/control-plane-atomic-uow.test.ts b/tests/control-plane-atomic-uow.test.ts new file mode 100644 index 00000000..011184cd --- /dev/null +++ b/tests/control-plane-atomic-uow.test.ts @@ -0,0 +1,382 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + AtomicCompanyControlPlane, +} from '@/lib/control-plane/atomic-engine'; + +import { + SqliteAtomicControlPlaneStore, +} from '@/lib/control-plane/sqlite-atomic-store'; + +let tempDir: string | null = null; + +const now = + '2026-01-01T00:00:00.000Z'; + +const retryPolicy = { + maxAttempts: 2, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, +}; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function databasePath(): string { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-cp-v2b-', + ), + ); + + return path.join( + tempDir, + 'control-plane.db', + ); +} + +function principal( + kind: 'agent' | 'human' | 'control_plane' | 'system', + id: string, +) { + return { + actor: { + kind, + id, + }, + }; +} + +function setup() { + const store = + new SqliteAtomicControlPlaneStore( + databasePath(), + ); + + const engine = + new AtomicCompanyControlPlane( + store, + () => now, + ); + + return { + store, + engine, + }; +} + +describe('Control Plane V2B atomic unit of work', () => { + test('commits workflow, command, idempotency, audit, event and outbox together', async () => { + const { store, engine } = setup(); + + const result = + await engine.createWorkflow({ + requestId: 'create-1', + workflowId: 'wf-1', + principal: principal( + 'agent', + 'lauti', + ), + responsibleResearchAgentId: + 'lauti', + assetRef: 'asset:test', + reason: 'Start research.', + metadata: {}, + }); + + expect(result.duplicate).toBe(false); + expect(result.workflow.state).toBe( + 'DRAFT', + ); + + expect( + await store.hasProcessedRequest( + 'create-1', + ), + ).toBe(true); + + expect( + store.listCommands('wf-1'), + ).toHaveLength(1); + + expect( + await store.listAudit('wf-1'), + ).toHaveLength(1); + + expect( + store.listDomainEvents('wf-1'), + ).toMatchObject([ + { + eventType: + 'workflow_created', + sequence: 0, + }, + ]); + + expect( + store.listOutbox(), + ).toMatchObject([ + { + status: 'pending', + topic: + 'control-plane.workflow.created', + }, + ]); + + store.close(); + }); + + test('same request id is idempotent and creates no duplicate durable records', async () => { + const { store, engine } = setup(); + + const request = { + requestId: 'same-request', + workflowId: 'wf-1', + principal: principal( + 'agent', + 'lauti', + ), + responsibleResearchAgentId: + 'lauti', + assetRef: 'asset:test', + reason: 'Start research.', + metadata: {}, + }; + + const first = + await engine.createWorkflow(request); + + const second = + await engine.createWorkflow(request); + + expect(first.duplicate).toBe(false); + expect(second.duplicate).toBe(true); + + expect( + store.listCommands('wf-1'), + ).toHaveLength(1); + + expect( + store.listDomainEvents('wf-1'), + ).toHaveLength(1); + + expect( + store.listOutbox(), + ).toHaveLength(1); + + store.close(); + }); + + test('rolls back all command state when a late outbox insert fails', async () => { + const { store, engine } = setup(); + + store.enqueueOutbox({ + messageId: + 'cp-outbox:create-rollback', + topic: 'preexisting.test', + partitionKey: 'preexisting', + createdAt: now, + availableAt: now, + retryPolicy, + payload: {}, + }); + + await expect( + engine.createWorkflow({ + requestId: 'create-rollback', + workflowId: 'wf-rollback', + principal: principal( + 'agent', + 'lauti', + ), + responsibleResearchAgentId: + 'lauti', + reason: 'Rollback proof.', + metadata: {}, + }), + ).rejects.toThrow(); + + expect( + await store.getWorkflow( + 'wf-rollback', + ), + ).toBeNull(); + + expect( + await store.hasProcessedRequest( + 'create-rollback', + ), + ).toBe(false); + + expect( + store.listCommands( + 'wf-rollback', + ), + ).toHaveLength(0); + + expect( + store.listDomainEvents( + 'wf-rollback', + ), + ).toHaveLength(0); + + expect( + await store.listAudit( + 'wf-rollback', + ), + ).toHaveLength(0); + + expect(store.listOutbox()).toHaveLength(1); + + store.close(); + }); + + test('transition and artifact mutations receive monotonic event sequences', async () => { + const { store, engine } = setup(); + + await engine.createWorkflow({ + requestId: 'create', + workflowId: 'wf-1', + principal: principal( + 'agent', + 'lauti', + ), + responsibleResearchAgentId: + 'lauti', + reason: 'Start.', + metadata: {}, + }); + + await engine.transition({ + requestId: 'to-research', + workflowId: 'wf-1', + principal: principal( + 'agent', + 'lauti', + ), + fromState: 'DRAFT', + toState: 'RESEARCHING', + expectedRevision: 0, + reason: 'Begin research.', + }); + + await engine.registerArtifact({ + requestId: 'proposal', + workflowId: 'wf-1', + principal: principal( + 'agent', + 'lauti', + ), + expectedRevision: 1, + artifact: { + id: 'proposal-1', + workflowId: 'wf-1', + kind: 'research_proposal', + createdBy: { + kind: 'agent', + id: 'lauti', + }, + createdAt: now, + summary: 'Proposal.', + metadata: {}, + }, + reason: 'Record proposal.', + }); + + const events = + store.listDomainEvents('wf-1'); + + expect( + events.map( + (event) => event.sequence, + ), + ).toEqual([0, 1, 2]); + + store.close(); + }); + + test('financial authorization is durably recorded and remains CEO-only', async () => { + const { store, engine } = setup(); + + const agentDecision = + await engine.authorizeFinancialAction({ + requestId: 'agent-buy', + principal: principal( + 'agent', + 'angelo', + ), + action: 'buy', + reason: 'Attempt execution.', + }); + + expect(agentDecision.allowed).toBe(false); + + const ceoDecision = + await engine.authorizeFinancialAction({ + requestId: 'ceo-buy', + principal: principal( + 'human', + 'ceo', + ), + action: 'buy', + reason: 'Human execution.', + }); + + expect(ceoDecision.allowed).toBe(true); + + const commands = + store.listCommands(); + + expect(commands).toHaveLength(2); + expect(commands[0]?.outcome).toBe( + 'denied', + ); + expect(commands[1]?.outcome).toBe( + 'succeeded', + ); + + const events = + store.listDomainEvents(); + + expect( + events.map( + (event) => event.eventType, + ), + ).toEqual([ + 'financial_action_denied', + 'financial_action_authorized', + ]); + + store.close(); + }); +}); From 4c9b2a528914f90f6cc598801d47510b39c6cb0e Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 19:31:33 +0200 Subject: [PATCH 47/62] Add reliable control plane consumers --- lib/control-plane/consumer-schema.ts | 63 ++ lib/control-plane/consumer.ts | 87 +++ lib/control-plane/index.ts | 7 +- lib/control-plane/outbox-worker.ts | 245 ++++++++ lib/control-plane/reliable-store.ts | 56 ++ lib/control-plane/sqlite-reliable-store.ts | 593 ++++++++++++++++++ .../control-plane-dead-letter-redrive.test.ts | 193 ++++++ .../control-plane-reliable-consumers.test.ts | 368 +++++++++++ 8 files changed, 1611 insertions(+), 1 deletion(-) create mode 100644 lib/control-plane/consumer-schema.ts create mode 100644 lib/control-plane/consumer.ts create mode 100644 lib/control-plane/outbox-worker.ts create mode 100644 lib/control-plane/reliable-store.ts create mode 100644 lib/control-plane/sqlite-reliable-store.ts create mode 100644 tests/control-plane-dead-letter-redrive.test.ts create mode 100644 tests/control-plane-reliable-consumers.test.ts diff --git a/lib/control-plane/consumer-schema.ts b/lib/control-plane/consumer-schema.ts new file mode 100644 index 00000000..cd5dc6c9 --- /dev/null +++ b/lib/control-plane/consumer-schema.ts @@ -0,0 +1,63 @@ +import { z } from 'zod'; + +import { + BrainActorSchema, + TimestampSchema, +} from '@/lib/brain/core-schema'; + +export const ConsumerDeliveryStatusSchema = z.enum([ + 'processing', + 'succeeded', +]); + +export const ConsumerDeliveryReceiptSchema = z.object({ + consumerId: z.string().min(1), + messageId: z.string().min(1), + topic: z.string().min(1), + + status: ConsumerDeliveryStatusSchema, + attempts: z.number().int().min(0), + + firstReceivedAt: TimestampSchema, + lastAttemptAt: TimestampSchema, + + completedAt: TimestampSchema.optional(), + + leaseOwner: z.string().min(1).optional(), + leaseUntil: TimestampSchema.optional(), + + lastError: z.string().optional(), + + result: z.record(z.unknown()).default({}), +}); + +export const ConsumerDeliveryClaimOutcomeSchema = z.enum([ + 'claimed', + 'already_succeeded', + 'busy', +]); + +export const ConsumerDeliveryClaimResultSchema = z.object({ + outcome: ConsumerDeliveryClaimOutcomeSchema, + receipt: ConsumerDeliveryReceiptSchema, +}); + +export const DeadLetterRedriveRecordSchema = z.object({ + redriveId: z.string().min(1), + messageId: z.string().min(1), + requestedBy: BrainActorSchema, + requestedAt: TimestampSchema, + reason: z.string().min(1), +}); + +export type ConsumerDeliveryReceipt = z.infer< + typeof ConsumerDeliveryReceiptSchema +>; + +export type ConsumerDeliveryClaimResult = z.infer< + typeof ConsumerDeliveryClaimResultSchema +>; + +export type DeadLetterRedriveRecord = z.infer< + typeof DeadLetterRedriveRecordSchema +>; diff --git a/lib/control-plane/consumer.ts b/lib/control-plane/consumer.ts new file mode 100644 index 00000000..ded63233 --- /dev/null +++ b/lib/control-plane/consumer.ts @@ -0,0 +1,87 @@ +import type { + ControlPlaneOutboxMessage, +} from '@/lib/control-plane/durable-schema'; + +export type ReliableConsumerContext = { + message: ControlPlaneOutboxMessage; + + /** + * Stable key that MUST be forwarded to an external provider when + * that provider supports idempotency. + * + * This protects the crash window between an external side effect + * and the local delivery receipt being committed. + */ + idempotencyKey: string; + + deliveryAttempt: number; +}; + +export type ReliableConsumerResult = { + result?: Record; +}; + +export interface ReliableOutboxConsumer { + id: string; + topics: readonly string[]; + + handle( + context: ReliableConsumerContext, + ): Promise; +} + +/** + * One topic resolves to exactly one consumer in V2C. + * + * If future workflows require fan-out, the producer must create one + * outbox message per destination rather than silently sharing one + * delivery receipt across multiple consumers. + */ +export class OutboxConsumerRegistry { + private readonly byTopic = + new Map(); + + register( + consumer: ReliableOutboxConsumer, + ): void { + if (!consumer.id.trim()) { + throw new Error( + 'consumer_id_required', + ); + } + + if (consumer.topics.length === 0) { + throw new Error( + `consumer_topics_required:${consumer.id}`, + ); + } + + for (const topic of consumer.topics) { + const existing = + this.byTopic.get(topic); + + if (existing) { + throw new Error( + `consumer_topic_already_registered:${topic}:${existing.id}`, + ); + } + + this.byTopic.set( + topic, + consumer, + ); + } + } + + resolve( + topic: string, + ): ReliableOutboxConsumer | null { + return this.byTopic.get(topic) ?? null; + } + + topics(): string[] { + return [ + ...this.byTopic.keys(), + ].sort(); + } +} diff --git a/lib/control-plane/index.ts b/lib/control-plane/index.ts index d99bf120..9a4db622 100644 --- a/lib/control-plane/index.ts +++ b/lib/control-plane/index.ts @@ -12,4 +12,9 @@ export * from '@/lib/control-plane/durable'; export * from '@/lib/control-plane/sqlite-store'; export * from '@/lib/control-plane/atomic-store'; export * from '@/lib/control-plane/sqlite-atomic-store'; -export * from '@/lib/control-plane/atomic-engine'; \ No newline at end of file +export * from '@/lib/control-plane/atomic-engine'; +export * from '@/lib/control-plane/consumer-schema'; +export * from '@/lib/control-plane/consumer'; +export * from '@/lib/control-plane/reliable-store'; +export * from '@/lib/control-plane/sqlite-reliable-store'; +export * from '@/lib/control-plane/outbox-worker'; \ No newline at end of file diff --git a/lib/control-plane/outbox-worker.ts b/lib/control-plane/outbox-worker.ts new file mode 100644 index 00000000..f767a15c --- /dev/null +++ b/lib/control-plane/outbox-worker.ts @@ -0,0 +1,245 @@ +import { + OutboxConsumerRegistry, +} from '@/lib/control-plane/consumer'; + +import type { + ReliableConsumerStore, +} from '@/lib/control-plane/reliable-store'; + +export type ReliableOutboxWorkerOptions = { + workerId: string; + batchSize: number; + outboxLeaseMs: number; + consumerLeaseMs: number; +}; + +export type ReliableOutboxWorkerRunResult = { + claimed: number; + succeeded: number; + deduplicated: number; + failed: number; + busy: number; + missingConsumer: number; +}; + +function errorMessage( + error: unknown, +): string { + return error instanceof Error + ? error.message + : String(error); +} + +/** + * Delivery semantics: + * + * - Outbox transport is at-least-once. + * - Successful consumer receipts are persistent. + * - A repeated outbox delivery whose receipt already succeeded skips + * the handler and only acknowledges the outbox message. + * - A handler MUST use the stable idempotencyKey for any external + * side effect when the provider supports idempotency. + * + * This intentionally does not claim impossible distributed + * exactly-once semantics. + */ +export class ReliableOutboxWorker { + constructor( + private readonly store: ReliableConsumerStore, + private readonly registry: OutboxConsumerRegistry, + private readonly options: ReliableOutboxWorkerOptions, + ) { + if (!options.workerId.trim()) { + throw new Error( + 'outbox_worker_id_required', + ); + } + + if (options.batchSize <= 0) { + throw new Error( + 'outbox_worker_batch_size_must_be_positive', + ); + } + + if ( + options.outboxLeaseMs <= 0 || + options.consumerLeaseMs <= 0 + ) { + throw new Error( + 'outbox_worker_lease_must_be_positive', + ); + } + } + + async runOnce( + now: string, + ): Promise { + const messages = + this.store.claimOutbox({ + workerId: + this.options.workerId, + now, + limit: + this.options.batchSize, + leaseMs: + this.options.outboxLeaseMs, + }); + + const stats: ReliableOutboxWorkerRunResult = { + claimed: messages.length, + succeeded: 0, + deduplicated: 0, + failed: 0, + busy: 0, + missingConsumer: 0, + }; + + for (const message of messages) { + const consumer = + this.registry.resolve( + message.topic, + ); + + if (!consumer) { + stats.missingConsumer += 1; + stats.failed += 1; + + this.store.failOutbox({ + messageId: + message.messageId, + workerId: + this.options.workerId, + failedAt: now, + error: + `no_consumer_registered:${message.topic}`, + }); + + continue; + } + + const claim = + this.store.claimConsumerDelivery({ + consumerId: consumer.id, + messageId: + message.messageId, + topic: + message.topic, + workerId: + this.options.workerId, + now, + leaseMs: + this.options.consumerLeaseMs, + }); + + if ( + claim.outcome === + 'already_succeeded' + ) { + this.store.acknowledgeOutbox({ + messageId: + message.messageId, + workerId: + this.options.workerId, + publishedAt: now, + }); + + stats.deduplicated += 1; + continue; + } + + if ( + claim.outcome === 'busy' + ) { + this.store.failOutbox({ + messageId: + message.messageId, + workerId: + this.options.workerId, + failedAt: now, + error: + `consumer_delivery_busy:${consumer.id}:${message.messageId}`, + }); + + stats.busy += 1; + stats.failed += 1; + continue; + } + + const idempotencyKey = + `${consumer.id}:${message.messageId}`; + + let consumerResult: + | Record + | undefined; + + try { + const handled = + await consumer.handle({ + message, + idempotencyKey, + deliveryAttempt: + claim.receipt.attempts, + }); + + consumerResult = + handled.result; + } catch (error) { + const reason = + errorMessage(error); + + this.store.failConsumerDelivery({ + consumerId: consumer.id, + messageId: + message.messageId, + workerId: + this.options.workerId, + failedAt: now, + error: reason, + }); + + this.store.failOutbox({ + messageId: + message.messageId, + workerId: + this.options.workerId, + failedAt: now, + error: reason, + }); + + stats.failed += 1; + continue; + } + + /* + * Important ordering: + * + * 1. persist successful consumer receipt + * 2. acknowledge outbox + * + * If the process crashes between 1 and 2, the next delivery + * sees already_succeeded and does not execute the consumer again. + */ + this.store.completeConsumerDelivery({ + consumerId: consumer.id, + messageId: + message.messageId, + workerId: + this.options.workerId, + completedAt: now, + result: consumerResult, + }); + + this.store.acknowledgeOutbox({ + messageId: + message.messageId, + workerId: + this.options.workerId, + publishedAt: now, + }); + + stats.succeeded += 1; + } + + return stats; + } +} diff --git a/lib/control-plane/reliable-store.ts b/lib/control-plane/reliable-store.ts new file mode 100644 index 00000000..f367e4b8 --- /dev/null +++ b/lib/control-plane/reliable-store.ts @@ -0,0 +1,56 @@ +import type { + ConsumerDeliveryClaimResult, + ConsumerDeliveryReceipt, + DeadLetterRedriveRecord, +} from '@/lib/control-plane/consumer-schema'; + +import type { + ControlPlaneOutboxStore, +} from '@/lib/control-plane/durable'; + +export interface ReliableConsumerStore + extends ControlPlaneOutboxStore +{ + claimConsumerDelivery(input: { + consumerId: string; + messageId: string; + topic: string; + workerId: string; + now: string; + leaseMs: number; + }): ConsumerDeliveryClaimResult; + + completeConsumerDelivery(input: { + consumerId: string; + messageId: string; + workerId: string; + completedAt: string; + result?: Record; + }): ConsumerDeliveryReceipt; + + failConsumerDelivery(input: { + consumerId: string; + messageId: string; + workerId: string; + failedAt: string; + error: string; + }): ConsumerDeliveryReceipt; + + getConsumerDeliveryReceipt(input: { + consumerId: string; + messageId: string; + }): ConsumerDeliveryReceipt | null; + + listConsumerDeliveryReceipts( + consumerId?: string, + ): ConsumerDeliveryReceipt[]; + + redriveDeadLetter( + record: DeadLetterRedriveRecord, + availableAt: string, + ): void; + + listDeadLetterRedrives( + messageId?: string, + ): DeadLetterRedriveRecord[]; +} diff --git a/lib/control-plane/sqlite-reliable-store.ts b/lib/control-plane/sqlite-reliable-store.ts new file mode 100644 index 00000000..c7c6f30f --- /dev/null +++ b/lib/control-plane/sqlite-reliable-store.ts @@ -0,0 +1,593 @@ +import { + ConsumerDeliveryClaimResultSchema, + ConsumerDeliveryReceiptSchema, + DeadLetterRedriveRecordSchema, + type ConsumerDeliveryClaimResult, + type ConsumerDeliveryReceipt, + type DeadLetterRedriveRecord, +} from '@/lib/control-plane/consumer-schema'; + +import type { + ReliableConsumerStore, +} from '@/lib/control-plane/reliable-store'; + +import { + SqliteAtomicControlPlaneStore, +} from '@/lib/control-plane/sqlite-atomic-store'; + +const RELIABLE_CONSUMER_DDL = ` +CREATE TABLE IF NOT EXISTS cp_consumer_deliveries ( + consumer_id TEXT NOT NULL, + message_id TEXT NOT NULL, + topic TEXT NOT NULL, + + status TEXT NOT NULL, + attempts INTEGER NOT NULL, + + first_received_at TEXT NOT NULL, + last_attempt_at TEXT NOT NULL, + completed_at TEXT, + + lease_owner TEXT, + lease_until TEXT, + + last_error TEXT, + result_json TEXT NOT NULL, + + PRIMARY KEY (consumer_id, message_id) +); + +CREATE INDEX IF NOT EXISTS cp_consumer_deliveries_status_idx +ON cp_consumer_deliveries(consumer_id, status, lease_until); + +CREATE TABLE IF NOT EXISTS cp_dead_letter_redrives ( + redrive_id TEXT PRIMARY KEY, + message_id TEXT NOT NULL, + requested_by_json TEXT NOT NULL, + requested_at TEXT NOT NULL, + reason TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS cp_dead_letter_redrives_message_idx +ON cp_dead_letter_redrives(message_id, requested_at); +`; + +type DeliveryRow = { + consumer_id: string; + message_id: string; + topic: string; + + status: string; + attempts: number; + + first_received_at: string; + last_attempt_at: string; + completed_at: string | null; + + lease_owner: string | null; + lease_until: string | null; + + last_error: string | null; + result_json: string; +}; + +type RedriveRow = { + redrive_id: string; + message_id: string; + requested_by_json: string; + requested_at: string; + reason: string; +}; + +function parseJson( + value: string, +): T { + return JSON.parse(value) as T; +} + +function addMs( + iso: string, + milliseconds: number, +): string { + return new Date( + Date.parse(iso) + milliseconds, + ).toISOString(); +} + +function rowToDelivery( + row: DeliveryRow, +): ConsumerDeliveryReceipt { + return ConsumerDeliveryReceiptSchema.parse({ + consumerId: row.consumer_id, + messageId: row.message_id, + topic: row.topic, + + status: row.status, + attempts: row.attempts, + + firstReceivedAt: + row.first_received_at, + lastAttemptAt: + row.last_attempt_at, + + completedAt: + row.completed_at ?? undefined, + + leaseOwner: + row.lease_owner ?? undefined, + leaseUntil: + row.lease_until ?? undefined, + + lastError: + row.last_error ?? undefined, + + result: parseJson( + row.result_json, + ), + }); +} + +function rowToRedrive( + row: RedriveRow, +): DeadLetterRedriveRecord { + return DeadLetterRedriveRecordSchema.parse({ + redriveId: row.redrive_id, + messageId: row.message_id, + requestedBy: parseJson( + row.requested_by_json, + ), + requestedAt: row.requested_at, + reason: row.reason, + }); +} + +export class SqliteReliableControlPlaneStore + extends SqliteAtomicControlPlaneStore + implements ReliableConsumerStore +{ + constructor(dbPath: string) { + super(dbPath); + + this.db.exec( + RELIABLE_CONSUMER_DDL, + ); + } + + claimConsumerDelivery(input: { + consumerId: string; + messageId: string; + topic: string; + workerId: string; + now: string; + leaseMs: number; + }): ConsumerDeliveryClaimResult { + if (input.leaseMs <= 0) { + throw new Error( + 'consumer_delivery_lease_must_be_positive', + ); + } + + const leaseUntil = addMs( + input.now, + input.leaseMs, + ); + + const transaction = + this.db.transaction(() => { + const existing = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as + | DeliveryRow + | undefined; + + if (!existing) { + this.db + .prepare( + `INSERT INTO cp_consumer_deliveries + ( + consumer_id, + message_id, + topic, + status, + attempts, + first_received_at, + last_attempt_at, + completed_at, + lease_owner, + lease_until, + last_error, + result_json + ) + VALUES (?, ?, ?, 'processing', 1, ?, ?, NULL, ?, ?, NULL, '{}')`, + ) + .run( + input.consumerId, + input.messageId, + input.topic, + input.now, + input.now, + input.workerId, + leaseUntil, + ); + + const inserted = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as DeliveryRow; + + return ConsumerDeliveryClaimResultSchema.parse({ + outcome: 'claimed', + receipt: rowToDelivery( + inserted, + ), + }); + } + + const receipt = + rowToDelivery(existing); + + if ( + receipt.status === + 'succeeded' + ) { + return ConsumerDeliveryClaimResultSchema.parse({ + outcome: + 'already_succeeded', + receipt, + }); + } + + const leaseStillActive = + receipt.leaseUntil !== undefined && + Date.parse( + receipt.leaseUntil, + ) > Date.parse(input.now); + + if (leaseStillActive) { + return ConsumerDeliveryClaimResultSchema.parse({ + outcome: 'busy', + receipt, + }); + } + + const result = this.db + .prepare( + `UPDATE cp_consumer_deliveries + SET attempts = attempts + 1, + last_attempt_at = ?, + lease_owner = ?, + lease_until = ?, + last_error = NULL + WHERE consumer_id = ? + AND message_id = ? + AND status = 'processing' + AND ( + lease_until IS NULL + OR lease_until <= ? + )`, + ) + .run( + input.now, + input.workerId, + leaseUntil, + input.consumerId, + input.messageId, + input.now, + ); + + if (result.changes !== 1) { + const current = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as DeliveryRow; + + return ConsumerDeliveryClaimResultSchema.parse({ + outcome: 'busy', + receipt: + rowToDelivery(current), + }); + } + + const claimed = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as DeliveryRow; + + return ConsumerDeliveryClaimResultSchema.parse({ + outcome: 'claimed', + receipt: + rowToDelivery(claimed), + }); + }); + + return transaction(); + } + + completeConsumerDelivery(input: { + consumerId: string; + messageId: string; + workerId: string; + completedAt: string; + result?: Record; + }): ConsumerDeliveryReceipt { + const result = this.db + .prepare( + `UPDATE cp_consumer_deliveries + SET status = 'succeeded', + completed_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = NULL, + result_json = ? + WHERE consumer_id = ? + AND message_id = ? + AND status = 'processing' + AND lease_owner = ?`, + ) + .run( + input.completedAt, + JSON.stringify( + input.result ?? {}, + ), + input.consumerId, + input.messageId, + input.workerId, + ); + + if (result.changes !== 1) { + throw new Error( + `consumer_delivery_complete_lease_mismatch:${input.consumerId}:${input.messageId}`, + ); + } + + const row = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as DeliveryRow; + + return rowToDelivery(row); + } + + failConsumerDelivery(input: { + consumerId: string; + messageId: string; + workerId: string; + failedAt: string; + error: string; + }): ConsumerDeliveryReceipt { + const result = this.db + .prepare( + `UPDATE cp_consumer_deliveries + SET last_attempt_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = ? + WHERE consumer_id = ? + AND message_id = ? + AND status = 'processing' + AND lease_owner = ?`, + ) + .run( + input.failedAt, + input.error, + input.consumerId, + input.messageId, + input.workerId, + ); + + if (result.changes !== 1) { + throw new Error( + `consumer_delivery_fail_lease_mismatch:${input.consumerId}:${input.messageId}`, + ); + } + + const row = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as DeliveryRow; + + return rowToDelivery(row); + } + + getConsumerDeliveryReceipt(input: { + consumerId: string; + messageId: string; + }): ConsumerDeliveryReceipt | null { + const row = this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + AND message_id = ?`, + ) + .get( + input.consumerId, + input.messageId, + ) as + | DeliveryRow + | undefined; + + return row + ? rowToDelivery(row) + : null; + } + + listConsumerDeliveryReceipts( + consumerId?: string, + ): ConsumerDeliveryReceipt[] { + const rows = consumerId + ? (this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + WHERE consumer_id = ? + ORDER BY first_received_at, rowid`, + ) + .all( + consumerId, + ) as DeliveryRow[]) + : (this.db + .prepare( + `SELECT * + FROM cp_consumer_deliveries + ORDER BY first_received_at, rowid`, + ) + .all() as DeliveryRow[]); + + return rows.map( + rowToDelivery, + ); + } + + redriveDeadLetter( + recordInput: DeadLetterRedriveRecord, + availableAt: string, + ): void { + const record = + DeadLetterRedriveRecordSchema.parse( + recordInput, + ); + + const transaction = + this.db.transaction(() => { + const current = this.db + .prepare( + `SELECT status + FROM cp_outbox + WHERE message_id = ?`, + ) + .get( + record.messageId, + ) as + | { status: string } + | undefined; + + if (!current) { + throw new Error( + `outbox_message_not_found:${record.messageId}`, + ); + } + + if ( + current.status !== + 'dead_letter' + ) { + throw new Error( + `outbox_message_not_dead_letter:${record.messageId}`, + ); + } + + this.db + .prepare( + `INSERT INTO cp_dead_letter_redrives + ( + redrive_id, + message_id, + requested_by_json, + requested_at, + reason + ) + VALUES (?, ?, ?, ?, ?)`, + ) + .run( + record.redriveId, + record.messageId, + JSON.stringify( + record.requestedBy, + ), + record.requestedAt, + record.reason, + ); + + this.db + .prepare( + `UPDATE cp_outbox + SET status = 'pending', + attempts = 0, + available_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = NULL, + published_at = NULL + WHERE message_id = ? + AND status = 'dead_letter'`, + ) + .run( + availableAt, + record.messageId, + ); + }); + + transaction(); + } + + listDeadLetterRedrives( + messageId?: string, + ): DeadLetterRedriveRecord[] { + const rows = messageId + ? (this.db + .prepare( + `SELECT * + FROM cp_dead_letter_redrives + WHERE message_id = ? + ORDER BY requested_at, rowid`, + ) + .all( + messageId, + ) as RedriveRow[]) + : (this.db + .prepare( + `SELECT * + FROM cp_dead_letter_redrives + ORDER BY requested_at, rowid`, + ) + .all() as RedriveRow[]); + + return rows.map( + rowToRedrive, + ); + } +} diff --git a/tests/control-plane-dead-letter-redrive.test.ts b/tests/control-plane-dead-letter-redrive.test.ts new file mode 100644 index 00000000..904dd248 --- /dev/null +++ b/tests/control-plane-dead-letter-redrive.test.ts @@ -0,0 +1,193 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + OutboxConsumerRegistry, +} from '@/lib/control-plane/consumer'; + +import { + ReliableOutboxWorker, +} from '@/lib/control-plane/outbox-worker'; + +import { + SqliteReliableControlPlaneStore, +} from '@/lib/control-plane/sqlite-reliable-store'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function store() { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-redrive-', + ), + ); + + return new SqliteReliableControlPlaneStore( + path.join( + tempDir, + 'cp.db', + ), + ); +} + +describe('Control Plane dead-letter recovery', () => { + test('redrives a dead-letter message with an auditable recovery record', async () => { + const cp = store(); + + cp.enqueueOutbox({ + messageId: 'msg-dead', + topic: 'test.redrive', + partitionKey: 'wf-1', + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy: { + maxAttempts: 1, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, + }, + payload: {}, + }); + + let shouldFail = true; + + const registry = + new OutboxConsumerRegistry(); + + registry.register({ + id: 'redrive-consumer', + topics: ['test.redrive'], + async handle() { + if (shouldFail) { + throw new Error( + 'provider_unavailable', + ); + } + + return { + result: { + deliveredAfterRedrive: true, + }, + }; + }, + }); + + const worker = + new ReliableOutboxWorker( + cp, + registry, + { + workerId: 'worker-a', + batchSize: 10, + outboxLeaseMs: 10_000, + consumerLeaseMs: 10_000, + }, + ); + + const failed = + await worker.runOnce( + '2026-01-01T00:00:01.000Z', + ); + + expect(failed.failed).toBe(1); + + expect( + cp.listOutbox()[0], + ).toMatchObject({ + status: 'dead_letter', + attempts: 1, + }); + + shouldFail = false; + + cp.redriveDeadLetter( + { + redriveId: 'redrive-1', + messageId: 'msg-dead', + requestedBy: { + kind: 'human', + id: 'ceo', + }, + requestedAt: + '2026-01-01T00:00:02.000Z', + reason: + 'External provider recovered; retry authorized.', + }, + '2026-01-01T00:00:02.000Z', + ); + + expect( + cp.listDeadLetterRedrives( + 'msg-dead', + ), + ).toHaveLength(1); + + expect( + cp.listOutbox()[0], + ).toMatchObject({ + status: 'pending', + attempts: 0, + }); + + const recovered = + await worker.runOnce( + '2026-01-01T00:00:03.000Z', + ); + + expect( + recovered.succeeded, + ).toBe(1); + + expect( + cp.listOutbox()[0], + ).toMatchObject({ + status: 'published', + }); + + expect( + cp.getConsumerDeliveryReceipt({ + consumerId: + 'redrive-consumer', + messageId: 'msg-dead', + }), + ).toMatchObject({ + status: 'succeeded', + attempts: 2, + }); + + cp.close(); + }); +}); diff --git a/tests/control-plane-reliable-consumers.test.ts b/tests/control-plane-reliable-consumers.test.ts new file mode 100644 index 00000000..f6eca230 --- /dev/null +++ b/tests/control-plane-reliable-consumers.test.ts @@ -0,0 +1,368 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + OutboxConsumerRegistry, +} from '@/lib/control-plane/consumer'; + +import { + ReliableOutboxWorker, +} from '@/lib/control-plane/outbox-worker'; + +import { + SqliteReliableControlPlaneStore, +} from '@/lib/control-plane/sqlite-reliable-store'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function store() { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-consumers-', + ), + ); + + return new SqliteReliableControlPlaneStore( + path.join( + tempDir, + 'cp.db', + ), + ); +} + +const retryPolicy = { + maxAttempts: 3, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, +}; + +function enqueue( + cp: SqliteReliableControlPlaneStore, + messageId: string, + topic = 'control-plane.workflow.transitioned', +) { + cp.enqueueOutbox({ + messageId, + topic, + partitionKey: 'wf-1', + workflowId: 'wf-1', + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: { + eventId: `event:${messageId}`, + }, + }); +} + +describe('Reliable outbox consumers', () => { + test('delivers a message and persists a successful receipt', async () => { + const cp = store(); + enqueue(cp, 'msg-1'); + + const seenKeys: string[] = []; + + const registry = + new OutboxConsumerRegistry(); + + registry.register({ + id: 'test-consumer', + topics: [ + 'control-plane.workflow.transitioned', + ], + async handle(context) { + seenKeys.push( + context.idempotencyKey, + ); + + return { + result: { + handled: true, + }, + }; + }, + }); + + const worker = + new ReliableOutboxWorker( + cp, + registry, + { + workerId: 'worker-a', + batchSize: 10, + outboxLeaseMs: 10_000, + consumerLeaseMs: 10_000, + }, + ); + + const result = + await worker.runOnce( + '2026-01-01T00:00:01.000Z', + ); + + expect(result.succeeded).toBe(1); + + expect(seenKeys).toEqual([ + 'test-consumer:msg-1', + ]); + + expect( + cp.listOutbox()[0], + ).toMatchObject({ + status: 'published', + }); + + expect( + cp.getConsumerDeliveryReceipt({ + consumerId: + 'test-consumer', + messageId: 'msg-1', + }), + ).toMatchObject({ + status: 'succeeded', + attempts: 1, + result: { + handled: true, + }, + }); + + cp.close(); + }); + + test('does not execute the handler again after receipt success if process crashed before outbox acknowledgement', async () => { + const cp = store(); + enqueue(cp, 'msg-crash'); + + const firstClaim = + cp.claimOutbox({ + workerId: 'worker-old', + now: + '2026-01-01T00:00:01.000Z', + limit: 1, + leaseMs: 1_000, + }); + + expect(firstClaim).toHaveLength(1); + + const delivery = + cp.claimConsumerDelivery({ + consumerId: + 'test-consumer', + messageId: 'msg-crash', + topic: + 'control-plane.workflow.transitioned', + workerId: 'worker-old', + now: + '2026-01-01T00:00:01.000Z', + leaseMs: 1_000, + }); + + expect( + delivery.outcome, + ).toBe('claimed'); + + cp.completeConsumerDelivery({ + consumerId: + 'test-consumer', + messageId: 'msg-crash', + workerId: 'worker-old', + completedAt: + '2026-01-01T00:00:01.500Z', + result: { + sideEffectCompleted: true, + }, + }); + + /* + * Simulated crash: + * receipt succeeded, but acknowledgeOutbox was never called. + */ + + let handlerCalls = 0; + + const registry = + new OutboxConsumerRegistry(); + + registry.register({ + id: 'test-consumer', + topics: [ + 'control-plane.workflow.transitioned', + ], + async handle() { + handlerCalls += 1; + return {}; + }, + }); + + const worker = + new ReliableOutboxWorker( + cp, + registry, + { + workerId: 'worker-new', + batchSize: 10, + outboxLeaseMs: 10_000, + consumerLeaseMs: 10_000, + }, + ); + + const result = + await worker.runOnce( + '2026-01-01T00:00:03.000Z', + ); + + expect( + result.deduplicated, + ).toBe(1); + + expect(handlerCalls).toBe(0); + + expect( + cp.listOutbox()[0], + ).toMatchObject({ + status: 'published', + attempts: 2, + }); + + cp.close(); + }); + + test('retries a failed consumer and later succeeds with the same stable idempotency key', async () => { + const cp = store(); + enqueue(cp, 'msg-retry'); + + const keys: string[] = []; + let calls = 0; + + const registry = + new OutboxConsumerRegistry(); + + registry.register({ + id: 'retry-consumer', + topics: [ + 'control-plane.workflow.transitioned', + ], + async handle(context) { + calls += 1; + keys.push( + context.idempotencyKey, + ); + + if (calls === 1) { + throw new Error( + 'temporary_failure', + ); + } + + return { + result: { + recovered: true, + }, + }; + }, + }); + + const worker = + new ReliableOutboxWorker( + cp, + registry, + { + workerId: 'worker-a', + batchSize: 10, + outboxLeaseMs: 10_000, + consumerLeaseMs: 10_000, + }, + ); + + const first = + await worker.runOnce( + '2026-01-01T00:00:01.000Z', + ); + + expect(first.failed).toBe(1); + + const second = + await worker.runOnce( + '2026-01-01T00:00:02.000Z', + ); + + expect(second.succeeded).toBe(1); + + expect(keys).toEqual([ + 'retry-consumer:msg-retry', + 'retry-consumer:msg-retry', + ]); + + expect( + cp.getConsumerDeliveryReceipt({ + consumerId: + 'retry-consumer', + messageId: 'msg-retry', + }), + ).toMatchObject({ + status: 'succeeded', + attempts: 2, + }); + + cp.close(); + }); + + test('refuses multiple consumers for the same topic', () => { + const registry = + new OutboxConsumerRegistry(); + + registry.register({ + id: 'consumer-a', + topics: ['topic-a'], + async handle() { + return {}; + }, + }); + + expect(() => + registry.register({ + id: 'consumer-b', + topics: ['topic-a'], + async handle() { + return {}; + }, + }), + ).toThrow( + 'consumer_topic_already_registered', + ); + }); +}); From c85a7668ab4ef9cfe25e97bf379b9ee951c21983 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Mon, 21 Sep 2026 19:46:49 +0200 Subject: [PATCH 48/62] Add governed control plane handoff routing --- lib/control-plane/brain-handoff-sink.ts | 95 ++ lib/control-plane/handoff-dispatcher.ts | 201 ++++ lib/control-plane/handoff-policy.ts | 1015 ++++++++++++++++++ lib/control-plane/handoff-router.ts | 65 ++ lib/control-plane/handoff-schema.ts | 91 ++ lib/control-plane/handoff-store.ts | 53 + lib/control-plane/index.ts | 9 +- lib/control-plane/sqlite-handoff-store.ts | 605 +++++++++++ tests/control-plane-handoff-dispatch.test.ts | 232 ++++ tests/control-plane-handoff-policy.test.ts | 260 +++++ tests/control-plane-handoff-routing.test.ts | 186 ++++ 11 files changed, 2811 insertions(+), 1 deletion(-) create mode 100644 lib/control-plane/brain-handoff-sink.ts create mode 100644 lib/control-plane/handoff-dispatcher.ts create mode 100644 lib/control-plane/handoff-policy.ts create mode 100644 lib/control-plane/handoff-router.ts create mode 100644 lib/control-plane/handoff-schema.ts create mode 100644 lib/control-plane/handoff-store.ts create mode 100644 lib/control-plane/sqlite-handoff-store.ts create mode 100644 tests/control-plane-handoff-dispatch.test.ts create mode 100644 tests/control-plane-handoff-policy.test.ts create mode 100644 tests/control-plane-handoff-routing.test.ts diff --git a/lib/control-plane/brain-handoff-sink.ts b/lib/control-plane/brain-handoff-sink.ts new file mode 100644 index 00000000..08a9421d --- /dev/null +++ b/lib/control-plane/brain-handoff-sink.ts @@ -0,0 +1,95 @@ +import { + BrainMutationProposalSchema, + type BrainMutationProposalInput, +} from '@/lib/brain/gateway/schema'; + +import { + BrainGateway, +} from '@/lib/brain/gateway/gateway'; + +import type { + GovernedHandoff, +} from '@/lib/control-plane/handoff-schema'; + +import type { + GovernedHandoffSink, +} from '@/lib/control-plane/handoff-dispatcher'; + +/** + * The Control Plane intentionally does NOT fabricate Brain graph events. + * + * A memory composer translates a governed handoff into a structured + * BrainMutationProposal. That proposal still goes through BrainGateway + * permissions and remains only a proposal; this sink never commits it. + */ +export interface BrainHandoffMutationComposer { + compose(input: { + handoff: GovernedHandoff; + idempotencyKey: string; + }): Promise< + BrainMutationProposalInput | null + >; +} + +export class StartupBrainProposalHandoffSink + implements GovernedHandoffSink +{ + readonly id = + 'startup-brain-proposal-sink'; + + readonly destination = { + kind: 'startup_brain', + id: 'startup-brain', + } as const; + + constructor( + private readonly brainGateway: + BrainGateway, + private readonly composer: + BrainHandoffMutationComposer, + ) {} + + async deliver(input: { + handoff: GovernedHandoff; + idempotencyKey: string; + deliveryAttempt: number; + }) { + const proposalInput = + await this.composer.compose({ + handoff: input.handoff, + idempotencyKey: + input.idempotencyKey, + }); + + if (!proposalInput) { + return { + result: { + proposed: false, + reason: + 'memory_composer_judged_handoff_not_worth_persisting', + }, + }; + } + + const proposal = + BrainMutationProposalSchema.parse( + proposalInput, + ); + + const result = + await this.brainGateway.proposeMutation( + proposal, + ); + + return { + result: { + proposed: true, + proposalId: + result.proposal.proposalId, + graphRevision: + result.graphRevision, + status: result.status, + }, + }; + } +} diff --git a/lib/control-plane/handoff-dispatcher.ts b/lib/control-plane/handoff-dispatcher.ts new file mode 100644 index 00000000..a3301b95 --- /dev/null +++ b/lib/control-plane/handoff-dispatcher.ts @@ -0,0 +1,201 @@ +import type { + GovernedHandoff, + HandoffDestination, +} from '@/lib/control-plane/handoff-schema'; + +import type { + GovernedHandoffStore, +} from '@/lib/control-plane/handoff-store'; + +export type GovernedHandoffDeliveryContext = { + handoff: GovernedHandoff; + + /** + * Stable idempotency key for downstream systems. + * External or durable destinations should use this key whenever + * their API supports idempotency. + */ + idempotencyKey: string; + + deliveryAttempt: number; +}; + +export type GovernedHandoffDeliveryResult = { + result?: Record; +}; + +export interface GovernedHandoffSink { + id: string; + + destination: HandoffDestination; + + deliver( + context: GovernedHandoffDeliveryContext, + ): Promise; +} + +function destinationKey( + destination: HandoffDestination, +): string { + return `${destination.kind}:${destination.id}`; +} + +export class GovernedHandoffSinkRegistry { + private readonly sinks = + new Map(); + + register( + sink: GovernedHandoffSink, + ): void { + if (!sink.id.trim()) { + throw new Error( + 'handoff_sink_id_required', + ); + } + + const key = destinationKey( + sink.destination, + ); + + const existing = + this.sinks.get(key); + + if (existing) { + throw new Error( + `handoff_destination_already_registered:${key}:${existing.id}`, + ); + } + + this.sinks.set( + key, + sink, + ); + } + + resolve( + destination: HandoffDestination, + ): GovernedHandoffSink | null { + return ( + this.sinks.get( + destinationKey( + destination, + ), + ) ?? null + ); + } +} + +export type GovernedHandoffDispatcherOptions = { + workerId: string; + batchSize: number; + leaseMs: number; +}; + +export type GovernedHandoffDispatcherResult = { + claimed: number; + delivered: number; + failed: number; + missingSink: number; +}; + +function errorMessage( + error: unknown, +): string { + return error instanceof Error + ? error.message + : String(error); +} + +export class GovernedHandoffDispatcher { + constructor( + private readonly store: + GovernedHandoffStore, + private readonly registry: + GovernedHandoffSinkRegistry, + private readonly options: + GovernedHandoffDispatcherOptions, + ) {} + + async runOnce( + now: string, + ): Promise { + const handoffs = + this.store.claimHandoffs({ + workerId: + this.options.workerId, + now, + limit: + this.options.batchSize, + leaseMs: + this.options.leaseMs, + }); + + const stats: + GovernedHandoffDispatcherResult = { + claimed: handoffs.length, + delivered: 0, + failed: 0, + missingSink: 0, + }; + + for (const handoff of handoffs) { + const sink = + this.registry.resolve( + handoff.destination, + ); + + if (!sink) { + stats.failed += 1; + stats.missingSink += 1; + + this.store.failHandoff({ + handoffId: + handoff.handoffId, + workerId: + this.options.workerId, + failedAt: now, + error: + `handoff_sink_not_registered:${destinationKey( + handoff.destination, + )}`, + }); + + continue; + } + + try { + await sink.deliver({ + handoff, + idempotencyKey: + `handoff:${handoff.handoffId}`, + deliveryAttempt: + handoff.attempts, + }); + + this.store.completeHandoff({ + handoffId: + handoff.handoffId, + workerId: + this.options.workerId, + deliveredAt: now, + }); + + stats.delivered += 1; + } catch (error) { + this.store.failHandoff({ + handoffId: + handoff.handoffId, + workerId: + this.options.workerId, + failedAt: now, + error: + errorMessage(error), + }); + + stats.failed += 1; + } + } + + return stats; + } +} diff --git a/lib/control-plane/handoff-policy.ts b/lib/control-plane/handoff-policy.ts new file mode 100644 index 00000000..a9c93142 --- /dev/null +++ b/lib/control-plane/handoff-policy.ts @@ -0,0 +1,1015 @@ +import { z } from 'zod'; + +import type { + ControlPlaneOutboxMessage, +} from '@/lib/control-plane/durable-schema'; + +import { + InvestmentWorkflowStateSchema, + WorkflowArtifactKindSchema, + type InvestmentWorkflow, + type InvestmentWorkflowState, +} from '@/lib/control-plane/schema'; + +import { + canTransitionState, +} from '@/lib/control-plane/state-machine'; + +import type { + GovernedHandoffInput, + GovernedHandoffKind, + HandoffDestination, +} from '@/lib/control-plane/handoff-schema'; + +const DEFAULT_HANDOFF_RETRY_POLICY = { + maxAttempts: 5, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 60_000, + timeoutMs: 30_000, +} as const; + +export const CONTROL_PLANE_ROUTABLE_TOPICS = [ + 'control-plane.workflow.created', + 'control-plane.artifact.registered', + 'control-plane.workflow.transitioned', + 'control-plane.invalidation.recorded', + 'control-plane.invalidation.resolved', + 'control-plane.financial-action.authorized', + 'control-plane.financial-action.denied', +] as const; + +const TransitionPayloadSchema = z.object({ + eventId: z.string().min(1), + eventType: z.literal( + 'workflow_transitioned', + ), + fromState: + InvestmentWorkflowStateSchema, + toState: + InvestmentWorkflowStateSchema, +}); + +const ArtifactPayloadSchema = z.object({ + eventId: z.string().min(1), + eventType: z.literal( + 'artifact_registered', + ), + artifactId: z.string().min(1), + artifactKind: + WorkflowArtifactKindSchema, +}); + +const InvalidationRecordedPayloadSchema = + z.object({ + eventId: z.string().min(1), + eventType: z.literal( + 'invalidation_recorded', + ), + invalidationId: z.string().min(1), + invalidationKind: + z.string().min(1), + }); + +const InvalidationResolvedPayloadSchema = + z.object({ + eventId: z.string().min(1), + eventType: z.literal( + 'invalidation_resolved', + ), + invalidationId: z.string().min(1), + }); + +const FinancialPayloadSchema = z.object({ + eventId: z.string().min(1), + eventType: z.enum([ + 'financial_action_authorized', + 'financial_action_denied', + ]), + financialAction: z.string().min(1), + allowed: z.boolean(), +}); + +function destinationKey( + destination: HandoffDestination, +): string { + return `${destination.kind}:${destination.id}`; +} + +function sanitizeIdPart( + value: string, +): string { + return value.replace( + /[^a-zA-Z0-9_.:-]/g, + '_', + ); +} + +function handoffId(input: { + messageId: string; + destination: HandoffDestination; + action: string; +}): string { + return [ + 'handoff', + sanitizeIdPart(input.messageId), + sanitizeIdPart( + destinationKey( + input.destination, + ), + ), + sanitizeIdPart(input.action), + ].join(':'); +} + +function makeHandoff(input: { + message: ControlPlaneOutboxMessage; + workflow?: InvestmentWorkflow; + stateAtEvent?: InvestmentWorkflowState; + kind: GovernedHandoffKind; + destination: HandoffDestination; + action: string; + summary: string; + policyEvidence: string[]; + payload?: Record; +}): GovernedHandoffInput { + return { + handoffId: handoffId({ + messageId: + input.message.messageId, + destination: + input.destination, + action: input.action, + }), + sourceMessageId: + input.message.messageId, + sourceTopic: + input.message.topic, + workflowId: + input.workflow?.id ?? + input.message.workflowId, + stateAtEvent: + input.stateAtEvent, + kind: input.kind, + destination: + input.destination, + action: input.action, + summary: input.summary, + createdAt: + input.message.createdAt, + availableAt: + input.message.availableAt, + retryPolicy: + DEFAULT_HANDOFF_RETRY_POLICY, + policyEvidence: + input.policyEvidence, + payload: { + ...input.message.payload, + ...(input.payload ?? {}), + }, + }; +} + +function activeArtifact( + workflow: InvestmentWorkflow, + kind: InvestmentWorkflow['artifacts'][number]['kind'], + authorId?: string, +) { + return workflow.artifacts.find( + (artifact) => + artifact.kind === kind && + artifact.status === 'active' && + ( + authorId === undefined || + artifact.createdBy.id === + authorId + ), + ); +} + +function requireArtifact( + workflow: InvestmentWorkflow, + kind: InvestmentWorkflow['artifacts'][number]['kind'], + authorId: string, + reason: string, +): void { + if ( + !activeArtifact( + workflow, + kind, + authorId, + ) + ) { + throw new Error( + `handoff_policy_precondition_failed:${reason}`, + ); + } +} + +function agentTask( + message: ControlPlaneOutboxMessage, + workflow: InvestmentWorkflow, + stateAtEvent: InvestmentWorkflowState, + agentId: string, + action: string, + summary: string, + evidence: string[], + payload: Record = {}, +): GovernedHandoffInput { + return makeHandoff({ + message, + workflow, + stateAtEvent, + kind: 'agent_task', + destination: { + kind: 'agent', + id: agentId, + }, + action, + summary, + policyEvidence: evidence, + payload, + }); +} + +function monitoringTask( + message: ControlPlaneOutboxMessage, + workflow: InvestmentWorkflow, + stateAtEvent: InvestmentWorkflowState, + agentId: string, + action: string, + summary: string, + evidence: string[], +): GovernedHandoffInput { + return makeHandoff({ + message, + workflow, + stateAtEvent, + kind: 'monitoring_task', + destination: { + kind: 'agent', + id: agentId, + }, + action, + summary, + policyEvidence: evidence, + }); +} + +function memoryCandidate( + message: ControlPlaneOutboxMessage, + workflow: InvestmentWorkflow, + stateAtEvent: InvestmentWorkflowState, + action: string, + summary: string, + evidence: string[], +): GovernedHandoffInput { + return makeHandoff({ + message, + workflow, + stateAtEvent, + kind: 'memory_candidate', + destination: { + kind: 'startup_brain', + id: 'startup-brain', + }, + action, + summary, + policyEvidence: evidence, + payload: { + memoryPolicy: + 'candidate_only_no_automatic_permanent_commit', + }, + }); +} + +function planTransitionHandoffs( + message: ControlPlaneOutboxMessage, + workflow: InvestmentWorkflow, +): GovernedHandoffInput[] { + const payload = + TransitionPayloadSchema.parse( + message.payload, + ); + + if ( + !canTransitionState( + payload.fromState, + payload.toState, + ) + ) { + throw new Error( + `handoff_noncanonical_transition:${payload.fromState}->${payload.toState}`, + ); + } + + const to = payload.toState; + const result: GovernedHandoffInput[] = + []; + + switch (to) { + case 'DRAFT': + break; + + case 'RESEARCHING': + if ( + workflow.responsibleResearchAgentId + ) { + result.push( + agentTask( + message, + workflow, + to, + workflow.responsibleResearchAgentId, + 'continue_research', + 'Continue the governed investment research workflow.', + [ + 'workflow:DRAFT->RESEARCHING', + 'research_preparation_owned_by_responsible_researcher', + ], + ), + ); + } + break; + + case 'READY_FOR_RED_DESK': + result.push( + agentTask( + message, + workflow, + to, + 'yann', + 'perform_red_desk_review', + 'Critically review the research proposal without rewriting the original proposal.', + [ + 'mandatory_review:yann', + 'red_desk_cannot_rewrite_original_proposals', + ], + ), + ); + break; + + case 'UNDER_CRITICAL_REVIEW': + break; + + case 'READY_FOR_FINAL_RESEARCH_SUPERVISOR': + requireArtifact( + workflow, + 'red_desk_review', + 'yann', + 'yann_red_desk_review_required_before_beppe_handoff', + ); + + result.push( + agentTask( + message, + workflow, + to, + 'beppe', + 'prepare_final_research_brief', + 'Consolidate the proposal and Red Desk objections for CEO review.', + [ + 'mandatory_review:beppe', + 'research_ceo_interface:beppe', + ], + ), + ); + break; + + case 'WAITING_CEO_RESEARCH_DECISION': + requireArtifact( + workflow, + 'final_research_brief', + 'beppe', + 'beppe_final_research_brief_required_before_ceo_handoff', + ); + + result.push( + makeHandoff({ + message, + workflow, + stateAtEvent: to, + kind: + 'ceo_approval_request', + destination: { + kind: 'human', + id: 'ceo', + }, + action: + 'decide_research_proposal', + summary: + 'Review the final research brief and approve or reject the proposal for risk analysis.', + policyEvidence: [ + 'research_final_decision:ceo', + 'research_ceo_interface:beppe', + 'ceo_research_approval_authorizes_risk_analysis_only', + ], + }), + ); + break; + + case 'CEO_RESEARCH_REJECTED': + result.push( + memoryCandidate( + message, + workflow, + to, + 'capture_rejected_research_decision', + 'Consider the rejected research proposal and rationale as an institutional-memory candidate.', + [ + 'memory:preserve_decisions', + 'memory:learn_from_failures_and_neutral_outcomes', + ], + ), + ); + break; + + case 'CEO_RESEARCH_APPROVED': + result.push( + memoryCandidate( + message, + workflow, + to, + 'capture_ceo_research_decision', + 'Consider the CEO research approval as a contextualized institutional-memory candidate.', + [ + 'memory:preserve_decisions', + 'no_single_event_automatic_generalization', + ], + ), + ); + break; + + case 'RISK_ANALYSIS': + for (const [ + agentId, + action, + summary, + ] of [ + [ + 'manuel', + 'analyze_portfolio_risk', + 'Assess portfolio-level risk and maximum permissible allocation under approved policy.', + ], + [ + 'dimash', + 'structure_trade', + 'Structure entry, sizing, stop, targets, duration and risk/reward.', + ], + [ + 'bare', + 'analyze_liquidity_and_events', + 'Assess liquidity, execution quality and material event risk.', + ], + [ + 'angelo', + 'prepare_broker_neutral_instructions', + 'Translate the financial plan into broker-neutral manual execution instructions.', + ], + ] as const) { + result.push( + agentTask( + message, + workflow, + to, + agentId, + action, + summary, + [ + `mandatory_risk_analysis:${agentId}`, + 'agents_cannot_execute_trades', + ], + ), + ); + } + break; + + case 'RISK_REVIEW': + result.push( + agentTask( + message, + workflow, + to, + 'pio', + 'perform_independent_risk_review', + 'Independently review the complete risk plan and issue the governed verdict.', + [ + 'independent_risk_review:pio', + 'pio_cannot_directly_modify_reviewed_plan', + ], + ), + ); + break; + + case 'RISK_REJECTED': + result.push( + memoryCandidate( + message, + workflow, + to, + 'capture_risk_rejection', + 'Consider the rejected risk plan and independent review as an institutional-memory candidate.', + [ + 'memory:learn_from_failures', + 'memory:preserve_risk_reviews', + ], + ), + ); + break; + + case 'RISK_MODIFICATION_REQUIRED': + for (const agentId of [ + 'manuel', + 'dimash', + 'bare', + 'angelo', + ] as const) { + result.push( + agentTask( + message, + workflow, + to, + agentId, + 'revise_risk_plan', + 'Revise the risk plan in response to the independent review without bypassing governance.', + [ + 'risk_review:modification_required', + 'risk_modification_returns_to_risk_analysis', + ], + ), + ); + } + + result.push( + memoryCandidate( + message, + workflow, + to, + 'capture_risk_modification_requirement', + 'Consider the required risk-plan correction and its cause as an institutional-memory candidate.', + [ + 'memory:preserve_reviews', + 'memory:preserve_disagreements', + ], + ), + ); + break; + + case 'RISK_APPROVED': + result.push( + memoryCandidate( + message, + workflow, + to, + 'capture_risk_approval', + 'Consider the approved risk structure and review evidence as an institutional-memory candidate.', + [ + 'memory:preserve_risk_reviews', + 'memory:preserve_decisions', + ], + ), + ); + break; + + case 'WAITING_CEO_EXECUTION': + requireArtifact( + workflow, + 'final_risk_ticket', + 'christian', + 'christian_final_risk_ticket_required_before_ceo_execution_handoff', + ); + + result.push( + makeHandoff({ + message, + workflow, + stateAtEvent: to, + kind: + 'ceo_approval_request', + destination: { + kind: 'human', + id: 'ceo', + }, + action: + 'perform_manual_execution_decision', + summary: + 'Review the definitive Trade Execution Ticket and decide whether to execute manually.', + policyEvidence: [ + 'execution_actor:ceo', + 'risk_ceo_interface:christian', + 'agents_allowed_execution:false', + ], + }), + ); + break; + + case 'CEO_EXECUTION_CONFIRMED': + result.push( + memoryCandidate( + message, + workflow, + to, + 'capture_execution_confirmation', + 'Consider the human execution confirmation as a decision-history memory candidate.', + [ + 'memory:preserve_decisions', + 'audit:preserve_execution_confirmation', + ], + ), + ); + break; + + case 'MONITORING': + requireArtifact( + workflow, + 'ceo_execution_confirmation', + 'ceo', + 'ceo_execution_confirmation_required_before_monitoring_handoff', + ); + + result.push( + monitoringTask( + message, + workflow, + to, + 'john', + 'monitor_open_position', + 'Monitor the open position against the original thesis and Trade Execution Ticket.', + [ + 'monitoring:position_monitoring:john', + ], + ), + monitoringTask( + message, + workflow, + to, + 'ale', + 'monitor_portfolio_exposure_and_events', + 'Monitor portfolio exposure, correlations, liquidity and the unified event calendar.', + [ + 'monitoring:exposure_event_watch:ale', + ], + ), + monitoringTask( + message, + workflow, + to, + 'carlos', + 'track_realized_vs_expected_performance', + 'Track realized outcomes against the pre-outcome forecast and benchmark.', + [ + 'monitoring:performance_analytics:carlos', + ], + ), + monitoringTask( + message, + workflow, + to, + 'javier', + 'supervise_monitoring_cycle', + 'Supervise the monitoring cycle and consolidate material alerts and reports.', + [ + 'monitoring_ceo_interface:javier', + 'monitoring_final_supervisor:javier', + ], + ), + ); + break; + + case 'CLOSED': + result.push( + monitoringTask( + message, + workflow, + to, + 'carlos', + 'finalize_performance_evaluation', + 'Finalize the investment performance evaluation using predefined criteria and coherent benchmarks.', + [ + 'performance_quality_separate_from_outcome', + ], + ), + monitoringTask( + message, + workflow, + to, + 'hakan', + 'finalize_employee_kpi_review_inputs', + 'Prepare role-specific KPI and audit inputs without altering historical operational outputs.', + [ + 'kpi_evaluator_independence', + ], + ), + ); + break; + + case 'POST_MORTEM': + result.push( + monitoringTask( + message, + workflow, + to, + 'zielu', + 'conduct_post_mortem', + 'Conduct the governed post-mortem and identify evidence-backed learning candidates.', + [ + 'learning_process_improvement:zielu', + 'do_not_generalize_from_single_failure', + ], + ), + monitoringTask( + message, + workflow, + to, + 'javier', + 'supervise_post_mortem_completion', + 'Supervise post-mortem completeness before archival.', + [ + 'monitoring_final_supervisor:javier', + ], + ), + ); + break; + + case 'ARCHIVED': + result.push( + memoryCandidate( + message, + workflow, + to, + 'compose_archived_workflow_experience', + 'Compose the completed workflow into contextualized institutional-memory proposals without automatically creating validated lessons.', + [ + 'memory:experience_creation', + 'memory:no_unreviewed_lesson_becomes_production_rule', + 'memory:preserve_context', + ], + ), + ); + break; + } + + return result; +} + +function planArtifactHandoffs( + message: ControlPlaneOutboxMessage, + workflow: InvestmentWorkflow, +): GovernedHandoffInput[] { + const payload = + ArtifactPayloadSchema.parse( + message.payload, + ); + + switch (payload.artifactKind) { + case 'red_desk_review': + return [ + agentTask( + message, + workflow, + workflow.state, + 'beppe', + 'review_red_desk_output', + 'Review the Red Desk output and prepare the final research brief when the workflow is ready.', + [ + 'research_ceo_interface:beppe', + 'mandatory_review:yann_then_beppe', + ], + { + artifactId: + payload.artifactId, + }, + ), + ]; + + case 'independent_risk_verdict': + return [ + agentTask( + message, + workflow, + workflow.state, + 'christian', + 'review_independent_risk_verdict', + 'Review Pio’s independent verdict and prepare the definitive risk output when permitted.', + [ + 'risk_final_supervisor:christian', + 'independent_risk_review:pio', + ], + { + artifactId: + payload.artifactId, + }, + ), + ]; + + case 'post_mortem': + return [ + memoryCandidate( + message, + workflow, + workflow.state, + 'compose_post_mortem_memory_proposal', + 'Compose the post-mortem into one or more governed Startup Brain mutation proposals.', + [ + 'memory:post_mortem', + 'memory:proposal_before_commit', + ], + ), + ]; + + default: + return []; + } +} + +function planInvalidationHandoffs( + message: ControlPlaneOutboxMessage, + workflow: InvestmentWorkflow, + resolved: boolean, +): GovernedHandoffInput[] { + const payload = resolved + ? InvalidationResolvedPayloadSchema.parse( + message.payload, + ) + : InvalidationRecordedPayloadSchema.parse( + message.payload, + ); + + const inRiskOrExecution = [ + 'RISK_ANALYSIS', + 'RISK_REVIEW', + 'RISK_MODIFICATION_REQUIRED', + 'RISK_APPROVED', + 'WAITING_CEO_EXECUTION', + ].includes(workflow.state); + + const destinationAgent = + inRiskOrExecution + ? 'christian' + : 'javier'; + + const action = resolved + ? 'review_resolved_material_invalidation' + : 'review_material_invalidation'; + + const result: GovernedHandoffInput[] = [ + makeHandoff({ + message, + workflow, + stateAtEvent: + workflow.state, + kind: + inRiskOrExecution + ? 'agent_task' + : 'monitoring_task', + destination: { + kind: 'agent', + id: destinationAgent, + }, + action, + summary: resolved + ? 'Review the resolved material invalidation and determine the governed next step.' + : 'Review the material invalidation and coordinate the governed response.', + policyEvidence: [ + inRiskOrExecution + ? 'risk_ceo_interface:christian' + : 'monitoring_ceo_interface:javier', + 'material_change_requires_governed_reassessment', + ], + }), + ]; + + if (!resolved) { + result.push( + memoryCandidate( + message, + workflow, + workflow.state, + 'capture_material_invalidation', + 'Consider the material invalidation and resulting response as an institutional-memory candidate.', + [ + 'memory:contextualized_material_events_used_in_decisions', + ], + ), + ); + } + + return result; +} + +function planFinancialHandoffs( + message: ControlPlaneOutboxMessage, +): GovernedHandoffInput[] { + const payload = + FinancialPayloadSchema.parse( + message.payload, + ); + + if (payload.allowed) { + /* + * Deliberately no broker/exchange handoff. + * Authorization is not execution. The human CEO executes manually. + */ + return []; + } + + return [ + makeHandoff({ + message, + kind: 'security_alert', + destination: { + kind: 'human', + id: 'ceo', + }, + action: + 'review_denied_financial_action', + summary: + 'Review a financial action denied by the Control Plane.', + policyEvidence: [ + 'financial_execution_only_ceo', + 'agents_allowed_execution:false', + ], + payload: { + financialAction: + payload.financialAction, + allowed: false, + }, + }), + ]; +} + +export function planGovernedHandoffs(input: { + message: ControlPlaneOutboxMessage; + workflow?: InvestmentWorkflow; +}): GovernedHandoffInput[] { + const { + message, + workflow, + } = input; + + switch (message.topic) { + case 'control-plane.workflow.created': + return []; + + case 'control-plane.workflow.transitioned': + if (!workflow) { + throw new Error( + `handoff_workflow_required:${message.messageId}`, + ); + } + + return planTransitionHandoffs( + message, + workflow, + ); + + case 'control-plane.artifact.registered': + if (!workflow) { + throw new Error( + `handoff_workflow_required:${message.messageId}`, + ); + } + + return planArtifactHandoffs( + message, + workflow, + ); + + case 'control-plane.invalidation.recorded': + if (!workflow) { + throw new Error( + `handoff_workflow_required:${message.messageId}`, + ); + } + + return planInvalidationHandoffs( + message, + workflow, + false, + ); + + case 'control-plane.invalidation.resolved': + if (!workflow) { + throw new Error( + `handoff_workflow_required:${message.messageId}`, + ); + } + + return planInvalidationHandoffs( + message, + workflow, + true, + ); + + case 'control-plane.financial-action.authorized': + case 'control-plane.financial-action.denied': + return planFinancialHandoffs( + message, + ); + + default: + throw new Error( + `unroutable_control_plane_topic:${message.topic}`, + ); + } +} diff --git a/lib/control-plane/handoff-router.ts b/lib/control-plane/handoff-router.ts new file mode 100644 index 00000000..406f486a --- /dev/null +++ b/lib/control-plane/handoff-router.ts @@ -0,0 +1,65 @@ +import type { + ReliableOutboxConsumer, + ReliableConsumerResult, +} from '@/lib/control-plane/consumer'; + +import { + CONTROL_PLANE_ROUTABLE_TOPICS, + planGovernedHandoffs, +} from '@/lib/control-plane/handoff-policy'; + +import type { + GovernedHandoffStore, +} from '@/lib/control-plane/handoff-store'; + +export class GovernedHandoffRouterConsumer + implements ReliableOutboxConsumer +{ + readonly id = + 'governed-handoff-router'; + + readonly topics = + CONTROL_PLANE_ROUTABLE_TOPICS; + + constructor( + private readonly store: + GovernedHandoffStore, + ) {} + + async handle( + context: Parameters< + ReliableOutboxConsumer['handle'] + >[0], + ): Promise { + const workflow = + context.message.workflowId + ? await this.store.getWorkflow( + context.message.workflowId, + ) + : undefined; + + const plans = + planGovernedHandoffs({ + message: context.message, + workflow: + workflow ?? undefined, + }); + + const stored = + this.store.enqueueHandoffsIdempotent( + plans, + ); + + return { + result: { + handoffCount: + stored.length, + handoffIds: + stored.map( + (handoff) => + handoff.handoffId, + ), + }, + }; + } +} diff --git a/lib/control-plane/handoff-schema.ts b/lib/control-plane/handoff-schema.ts new file mode 100644 index 00000000..7ccc5f6a --- /dev/null +++ b/lib/control-plane/handoff-schema.ts @@ -0,0 +1,91 @@ +import { z } from 'zod'; + +import { + TimestampSchema, +} from '@/lib/brain/core-schema'; + +import { + InvestmentWorkflowStateSchema, +} from '@/lib/control-plane/schema'; + +import { + RetryPolicySchema, +} from '@/lib/control-plane/jobs'; + +export const GovernedHandoffKindSchema = z.enum([ + 'agent_task', + 'ceo_approval_request', + 'ceo_notification', + 'monitoring_task', + 'memory_candidate', + 'security_alert', +]); + +export const HandoffDestinationKindSchema = z.enum([ + 'agent', + 'human', + 'department', + 'startup_brain', +]); + +export const HandoffDestinationSchema = z.object({ + kind: HandoffDestinationKindSchema, + id: z.string().min(1), +}); + +export const GovernedHandoffStatusSchema = z.enum([ + 'pending', + 'in_flight', + 'delivered', + 'dead_letter', + 'cancelled', +]); + +export const GovernedHandoffSchema = z.object({ + handoffId: z.string().min(1), + + sourceMessageId: z.string().min(1), + sourceTopic: z.string().min(1), + + workflowId: z.string().min(1).optional(), + stateAtEvent: InvestmentWorkflowStateSchema.optional(), + + kind: GovernedHandoffKindSchema, + destination: HandoffDestinationSchema, + + action: z.string().min(1), + summary: z.string().min(1), + + status: GovernedHandoffStatusSchema.default('pending'), + attempts: z.number().int().min(0).default(0), + + createdAt: TimestampSchema, + availableAt: TimestampSchema, + + retryPolicy: RetryPolicySchema, + + leaseOwner: z.string().min(1).optional(), + leaseUntil: TimestampSchema.optional(), + + deliveredAt: TimestampSchema.optional(), + lastError: z.string().optional(), + + policyEvidence: z.array(z.string().min(1)).default([]), + payload: z.record(z.unknown()).default({}), +}); + +export type GovernedHandoff = z.infer< + typeof GovernedHandoffSchema +>; + +export type GovernedHandoffInput = z.input< + typeof GovernedHandoffSchema +>; + +export type HandoffDestination = z.infer< + typeof HandoffDestinationSchema +>; + +export type GovernedHandoffKind = z.infer< + typeof GovernedHandoffKindSchema +>; diff --git a/lib/control-plane/handoff-store.ts b/lib/control-plane/handoff-store.ts new file mode 100644 index 00000000..3ac54262 --- /dev/null +++ b/lib/control-plane/handoff-store.ts @@ -0,0 +1,53 @@ +import type { + GovernedHandoff, + GovernedHandoffInput, +} from '@/lib/control-plane/handoff-schema'; + +import type { + ReliableConsumerStore, +} from '@/lib/control-plane/reliable-store'; + +import type { + ControlPlaneStore, +} from '@/lib/control-plane/store'; + +export interface GovernedHandoffStore +extends ReliableConsumerStore, +ControlPlaneStore +{ + enqueueHandoffsIdempotent( + handoffs: GovernedHandoffInput[], + ): GovernedHandoff[]; + + listHandoffs(input?: { + workflowId?: string; + destinationKind?: GovernedHandoff['destination']['kind']; + destinationId?: string; + status?: GovernedHandoff['status']; + }): GovernedHandoff[]; + + claimHandoffs(input: { + workerId: string; + now: string; + limit: number; + leaseMs: number; + }): GovernedHandoff[]; + + completeHandoff(input: { + handoffId: string; + workerId: string; + deliveredAt: string; + }): GovernedHandoff; + + failHandoff(input: { + handoffId: string; + workerId: string; + failedAt: string; + error: string; + }): GovernedHandoff; + + cancelHandoff(input: { + handoffId: string; + reason: string; + }): GovernedHandoff; +} diff --git a/lib/control-plane/index.ts b/lib/control-plane/index.ts index 9a4db622..8b29edbe 100644 --- a/lib/control-plane/index.ts +++ b/lib/control-plane/index.ts @@ -17,4 +17,11 @@ export * from '@/lib/control-plane/consumer-schema'; export * from '@/lib/control-plane/consumer'; export * from '@/lib/control-plane/reliable-store'; export * from '@/lib/control-plane/sqlite-reliable-store'; -export * from '@/lib/control-plane/outbox-worker'; \ No newline at end of file +export * from '@/lib/control-plane/outbox-worker'; +export * from '@/lib/control-plane/handoff-schema'; +export * from '@/lib/control-plane/handoff-store'; +export * from '@/lib/control-plane/handoff-policy'; +export * from '@/lib/control-plane/sqlite-handoff-store'; +export * from '@/lib/control-plane/handoff-router'; +export * from '@/lib/control-plane/handoff-dispatcher'; +export * from '@/lib/control-plane/brain-handoff-sink'; \ No newline at end of file diff --git a/lib/control-plane/sqlite-handoff-store.ts b/lib/control-plane/sqlite-handoff-store.ts new file mode 100644 index 00000000..9449ca7b --- /dev/null +++ b/lib/control-plane/sqlite-handoff-store.ts @@ -0,0 +1,605 @@ +import { + GovernedHandoffSchema, + type GovernedHandoff, + type GovernedHandoffInput, +} from '@/lib/control-plane/handoff-schema'; + +import type { + GovernedHandoffStore, +} from '@/lib/control-plane/handoff-store'; + +import { + computeRetryDelayMs, +} from '@/lib/control-plane/jobs'; + +import { + SqliteReliableControlPlaneStore, +} from '@/lib/control-plane/sqlite-reliable-store'; + +const HANDOFF_DDL = ` +CREATE TABLE IF NOT EXISTS cp_handoffs ( + handoff_id TEXT PRIMARY KEY, + + source_message_id TEXT NOT NULL, + source_topic TEXT NOT NULL, + + workflow_id TEXT, + state_at_event TEXT, + + kind TEXT NOT NULL, + + destination_kind TEXT NOT NULL, + destination_id TEXT NOT NULL, + + action TEXT NOT NULL, + summary TEXT NOT NULL, + + status TEXT NOT NULL, + attempts INTEGER NOT NULL, + + created_at TEXT NOT NULL, + available_at TEXT NOT NULL, + + retry_policy_json TEXT NOT NULL, + + lease_owner TEXT, + lease_until TEXT, + + delivered_at TEXT, + last_error TEXT, + + policy_evidence_json TEXT NOT NULL, + payload_json TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS cp_handoffs_pending_idx +ON cp_handoffs(status, available_at, lease_until); + +CREATE INDEX IF NOT EXISTS cp_handoffs_destination_idx +ON cp_handoffs(destination_kind, destination_id, status); + +CREATE INDEX IF NOT EXISTS cp_handoffs_workflow_idx +ON cp_handoffs(workflow_id, created_at); +`; + +type HandoffRow = { + handoff_id: string; + + source_message_id: string; + source_topic: string; + + workflow_id: string | null; + state_at_event: string | null; + + kind: string; + + destination_kind: string; + destination_id: string; + + action: string; + summary: string; + + status: string; + attempts: number; + + created_at: string; + available_at: string; + + retry_policy_json: string; + + lease_owner: string | null; + lease_until: string | null; + + delivered_at: string | null; + last_error: string | null; + + policy_evidence_json: string; + payload_json: string; +}; + +function parseJson( + value: string, +): T { + return JSON.parse(value) as T; +} + +function addMs( + iso: string, + milliseconds: number, +): string { + return new Date( + Date.parse(iso) + milliseconds, + ).toISOString(); +} + +function rowToHandoff( + row: HandoffRow, +): GovernedHandoff { + return GovernedHandoffSchema.parse({ + handoffId: row.handoff_id, + + sourceMessageId: + row.source_message_id, + sourceTopic: + row.source_topic, + + workflowId: + row.workflow_id ?? undefined, + stateAtEvent: + row.state_at_event ?? undefined, + + kind: row.kind, + + destination: { + kind: + row.destination_kind, + id: + row.destination_id, + }, + + action: row.action, + summary: row.summary, + + status: row.status, + attempts: row.attempts, + + createdAt: + row.created_at, + availableAt: + row.available_at, + + retryPolicy: parseJson( + row.retry_policy_json, + ), + + leaseOwner: + row.lease_owner ?? undefined, + leaseUntil: + row.lease_until ?? undefined, + + deliveredAt: + row.delivered_at ?? undefined, + lastError: + row.last_error ?? undefined, + + policyEvidence: parseJson( + row.policy_evidence_json, + ), + payload: parseJson( + row.payload_json, + ), + }); +} + +export class SqliteGovernedHandoffStore + extends SqliteReliableControlPlaneStore + implements GovernedHandoffStore +{ + constructor(dbPath: string) { + super(dbPath); + + this.db.exec( + HANDOFF_DDL, + ); + } + + enqueueHandoffsIdempotent( + handoffInputs: GovernedHandoffInput[], + ): GovernedHandoff[] { + const handoffs = + handoffInputs.map((handoff) => + GovernedHandoffSchema.parse( + handoff, + ), + ); + + const transaction = + this.db.transaction(() => { + const insert = this.db.prepare( + `INSERT OR IGNORE INTO cp_handoffs + ( + handoff_id, + source_message_id, + source_topic, + workflow_id, + state_at_event, + kind, + destination_kind, + destination_id, + action, + summary, + status, + attempts, + created_at, + available_at, + retry_policy_json, + lease_owner, + lease_until, + delivered_at, + last_error, + policy_evidence_json, + payload_json + ) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ); + + const read = this.db.prepare( + `SELECT * + FROM cp_handoffs + WHERE handoff_id = ?`, + ); + + const stored: + GovernedHandoff[] = []; + + for (const handoff of handoffs) { + insert.run( + handoff.handoffId, + handoff.sourceMessageId, + handoff.sourceTopic, + handoff.workflowId ?? null, + handoff.stateAtEvent ?? null, + handoff.kind, + handoff.destination.kind, + handoff.destination.id, + handoff.action, + handoff.summary, + handoff.status, + handoff.attempts, + handoff.createdAt, + handoff.availableAt, + JSON.stringify( + handoff.retryPolicy, + ), + handoff.leaseOwner ?? null, + handoff.leaseUntil ?? null, + handoff.deliveredAt ?? null, + handoff.lastError ?? null, + JSON.stringify( + handoff.policyEvidence, + ), + JSON.stringify( + handoff.payload, + ), + ); + + stored.push( + rowToHandoff( + read.get( + handoff.handoffId, + ) as HandoffRow, + ), + ); + } + + return stored; + }); + + return transaction(); + } + + listHandoffs(input: { + workflowId?: string; + destinationKind?: GovernedHandoff['destination']['kind']; + destinationId?: string; + status?: GovernedHandoff['status']; + } = {}): GovernedHandoff[] { + const conditions: string[] = []; + const params: string[] = []; + + if (input.workflowId) { + conditions.push( + 'workflow_id = ?', + ); + params.push( + input.workflowId, + ); + } + + if (input.destinationKind) { + conditions.push( + 'destination_kind = ?', + ); + params.push( + input.destinationKind, + ); + } + + if (input.destinationId) { + conditions.push( + 'destination_id = ?', + ); + params.push( + input.destinationId, + ); + } + + if (input.status) { + conditions.push( + 'status = ?', + ); + params.push( + input.status, + ); + } + + const where = + conditions.length > 0 + ? `WHERE ${conditions.join( + ' AND ', + )}` + : ''; + + const rows = this.db + .prepare( + `SELECT * + FROM cp_handoffs + ${where} + ORDER BY created_at, rowid`, + ) + .all(...params) as HandoffRow[]; + + return rows.map( + rowToHandoff, + ); + } + + claimHandoffs(input: { + workerId: string; + now: string; + limit: number; + leaseMs: number; + }): GovernedHandoff[] { + if (input.limit <= 0) { + throw new Error( + 'handoff_claim_limit_must_be_positive', + ); + } + + if (input.leaseMs <= 0) { + throw new Error( + 'handoff_claim_lease_must_be_positive', + ); + } + + const leaseUntil = addMs( + input.now, + input.leaseMs, + ); + + const transaction = + this.db.transaction(() => { + const candidates = this.db + .prepare( + `SELECT handoff_id + FROM cp_handoffs + WHERE available_at <= ? + AND ( + status = 'pending' + OR ( + status = 'in_flight' + AND lease_until IS NOT NULL + AND lease_until <= ? + ) + ) + ORDER BY available_at, created_at, rowid + LIMIT ?`, + ) + .all( + input.now, + input.now, + input.limit, + ) as Array<{ + handoff_id: string; + }>; + + const update = this.db.prepare( + `UPDATE cp_handoffs + SET status = 'in_flight', + attempts = attempts + 1, + lease_owner = ?, + lease_until = ? + WHERE handoff_id = ? + AND ( + status = 'pending' + OR ( + status = 'in_flight' + AND lease_until IS NOT NULL + AND lease_until <= ? + ) + )`, + ); + + const read = this.db.prepare( + `SELECT * + FROM cp_handoffs + WHERE handoff_id = ?`, + ); + + const claimed: + GovernedHandoff[] = []; + + for (const candidate of candidates) { + const result = update.run( + input.workerId, + leaseUntil, + candidate.handoff_id, + input.now, + ); + + if (result.changes !== 1) { + continue; + } + + claimed.push( + rowToHandoff( + read.get( + candidate.handoff_id, + ) as HandoffRow, + ), + ); + } + + return claimed; + }); + + return transaction(); + } + + completeHandoff(input: { + handoffId: string; + workerId: string; + deliveredAt: string; + }): GovernedHandoff { + const result = this.db + .prepare( + `UPDATE cp_handoffs + SET status = 'delivered', + delivered_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = NULL + WHERE handoff_id = ? + AND status = 'in_flight' + AND lease_owner = ?`, + ) + .run( + input.deliveredAt, + input.handoffId, + input.workerId, + ); + + if (result.changes !== 1) { + throw new Error( + `handoff_complete_lease_mismatch:${input.handoffId}`, + ); + } + + return this.readHandoff( + input.handoffId, + ); + } + + failHandoff(input: { + handoffId: string; + workerId: string; + failedAt: string; + error: string; + }): GovernedHandoff { + const transaction = + this.db.transaction(() => { + const current = + this.readHandoff( + input.handoffId, + ); + + if ( + current.status !== + 'in_flight' || + current.leaseOwner !== + input.workerId + ) { + throw new Error( + `handoff_fail_lease_mismatch:${input.handoffId}`, + ); + } + + const exhausted = + current.attempts >= + current.retryPolicy.maxAttempts; + + const delayMs = + computeRetryDelayMs( + current.retryPolicy, + current.attempts, + ); + + const nextAvailableAt = + addMs( + input.failedAt, + delayMs, + ); + + this.db + .prepare( + `UPDATE cp_handoffs + SET status = ?, + available_at = ?, + lease_owner = NULL, + lease_until = NULL, + last_error = ? + WHERE handoff_id = ?`, + ) + .run( + exhausted + ? 'dead_letter' + : 'pending', + exhausted + ? current.availableAt + : nextAvailableAt, + input.error, + input.handoffId, + ); + + return this.readHandoff( + input.handoffId, + ); + }); + + return transaction(); + } + + cancelHandoff(input: { + handoffId: string; + reason: string; + }): GovernedHandoff { + const result = this.db + .prepare( + `UPDATE cp_handoffs + SET status = 'cancelled', + lease_owner = NULL, + lease_until = NULL, + last_error = ? + WHERE handoff_id = ? + AND status IN ('pending', 'in_flight')`, + ) + .run( + input.reason, + input.handoffId, + ); + + if (result.changes !== 1) { + throw new Error( + `handoff_not_cancellable:${input.handoffId}`, + ); + } + + return this.readHandoff( + input.handoffId, + ); + } + + private readHandoff( + handoffId: string, + ): GovernedHandoff { + const row = this.db + .prepare( + `SELECT * + FROM cp_handoffs + WHERE handoff_id = ?`, + ) + .get( + handoffId, + ) as + | HandoffRow + | undefined; + + if (!row) { + throw new Error( + `handoff_not_found:${handoffId}`, + ); + } + + return rowToHandoff(row); + } +} diff --git a/tests/control-plane-handoff-dispatch.test.ts b/tests/control-plane-handoff-dispatch.test.ts new file mode 100644 index 00000000..f8f2b143 --- /dev/null +++ b/tests/control-plane-handoff-dispatch.test.ts @@ -0,0 +1,232 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + GovernedHandoffDispatcher, + GovernedHandoffSinkRegistry, +} from '@/lib/control-plane/handoff-dispatcher'; + +import { + SqliteGovernedHandoffStore, +} from '@/lib/control-plane/sqlite-handoff-store'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function store() { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-handoff-dispatch-', + ), + ); + + return new SqliteGovernedHandoffStore( + path.join( + tempDir, + 'cp.db', + ), + ); +} + +describe('Governed handoff dispatcher', () => { + test('delivers to the exact registered destination with stable idempotency key', async () => { + const cp = store(); + + cp.enqueueHandoffsIdempotent([ + { + handoffId: + 'handoff:msg-1:agent:yann:perform_red_desk_review', + sourceMessageId: 'msg-1', + sourceTopic: + 'control-plane.workflow.transitioned', + workflowId: 'wf-1', + stateAtEvent: + 'READY_FOR_RED_DESK', + kind: 'agent_task', + destination: { + kind: 'agent', + id: 'yann', + }, + action: + 'perform_red_desk_review', + summary: + 'Perform Red Desk review.', + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy: { + maxAttempts: 3, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, + }, + policyEvidence: [ + 'mandatory_review:yann', + ], + payload: {}, + }, + ]); + + const keys: string[] = []; + + const registry = + new GovernedHandoffSinkRegistry(); + + registry.register({ + id: 'fake-yann-runtime', + destination: { + kind: 'agent', + id: 'yann', + }, + async deliver(context) { + keys.push( + context.idempotencyKey, + ); + + return { + result: { + accepted: true, + }, + }; + }, + }); + + const dispatcher = + new GovernedHandoffDispatcher( + cp, + registry, + { + workerId: + 'handoff-worker', + batchSize: 10, + leaseMs: 10_000, + }, + ); + + const result = + await dispatcher.runOnce( + '2026-01-01T00:00:01.000Z', + ); + + expect(result.delivered).toBe(1); + + expect(keys).toEqual([ + 'handoff:handoff:msg-1:agent:yann:perform_red_desk_review', + ]); + + expect( + cp.listHandoffs()[0], + ).toMatchObject({ + status: 'delivered', + attempts: 1, + }); + + cp.close(); + }); + + test('retries when destination runtime is not yet connected', async () => { + const cp = store(); + + cp.enqueueHandoffsIdempotent([ + { + handoffId: + 'handoff:msg-2:human:ceo:decide_research_proposal', + sourceMessageId: 'msg-2', + sourceTopic: + 'control-plane.workflow.transitioned', + workflowId: 'wf-2', + stateAtEvent: + 'WAITING_CEO_RESEARCH_DECISION', + kind: + 'ceo_approval_request', + destination: { + kind: 'human', + id: 'ceo', + }, + action: + 'decide_research_proposal', + summary: + 'CEO decision required.', + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy: { + maxAttempts: 3, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 10_000, + timeoutMs: 30_000, + }, + policyEvidence: [ + 'research_final_decision:ceo', + ], + payload: {}, + }, + ]); + + const registry = + new GovernedHandoffSinkRegistry(); + + const dispatcher = + new GovernedHandoffDispatcher( + cp, + registry, + { + workerId: + 'handoff-worker', + batchSize: 10, + leaseMs: 10_000, + }, + ); + + const result = + await dispatcher.runOnce( + '2026-01-01T00:00:01.000Z', + ); + + expect(result.missingSink).toBe(1); + + expect( + cp.listHandoffs()[0], + ).toMatchObject({ + status: 'pending', + attempts: 1, + lastError: + 'handoff_sink_not_registered:human:ceo', + }); + + cp.close(); + }); +}); diff --git a/tests/control-plane-handoff-policy.test.ts b/tests/control-plane-handoff-policy.test.ts new file mode 100644 index 00000000..ed3a97ea --- /dev/null +++ b/tests/control-plane-handoff-policy.test.ts @@ -0,0 +1,260 @@ +import { + describe, + expect, + test, +} from 'vitest'; + +import type { + ControlPlaneOutboxMessage, +} from '@/lib/control-plane/durable-schema'; + +import { + planGovernedHandoffs, +} from '@/lib/control-plane/handoff-policy'; + +import type { + InvestmentWorkflow, +} from '@/lib/control-plane/schema'; + +const retryPolicy = { + maxAttempts: 5, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 60_000, + timeoutMs: 30_000, +}; + +function workflow( + state: InvestmentWorkflow['state'], +): InvestmentWorkflow { + return { + id: 'wf-1', + state, + revision: 4, + createdBy: { + kind: 'agent', + id: 'lauti', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + updatedAt: + '2026-01-01T00:04:00.000Z', + responsibleResearchAgentId: + 'lauti', + artifacts: [], + invalidations: [], + metadata: {}, + }; +} + +function transitionMessage( + fromState: + InvestmentWorkflow['state'], + toState: + InvestmentWorkflow['state'], +): ControlPlaneOutboxMessage { + return { + messageId: + `msg:${fromState}:${toState}`, + topic: + 'control-plane.workflow.transitioned', + partitionKey: 'wf-1', + workflowId: 'wf-1', + status: 'pending', + attempts: 0, + createdAt: + '2026-01-01T00:04:00.000Z', + availableAt: + '2026-01-01T00:04:00.000Z', + retryPolicy, + payload: { + eventId: 'event-1', + eventType: + 'workflow_transitioned', + fromState, + toState, + }, + }; +} + +describe('Governed handoff policy', () => { + test('routes READY_FOR_RED_DESK to Yann', () => { + const handoffs = + planGovernedHandoffs({ + message: transitionMessage( + 'RESEARCHING', + 'READY_FOR_RED_DESK', + ), + workflow: workflow( + 'READY_FOR_RED_DESK', + ), + }); + + expect(handoffs).toHaveLength(1); + + expect( + handoffs[0], + ).toMatchObject({ + kind: 'agent_task', + destination: { + kind: 'agent', + id: 'yann', + }, + action: + 'perform_red_desk_review', + }); + }); + + test('CEO research handoff requires Beppe final brief', () => { + const current = workflow( + 'WAITING_CEO_RESEARCH_DECISION', + ); + + expect(() => + planGovernedHandoffs({ + message: transitionMessage( + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR', + 'WAITING_CEO_RESEARCH_DECISION', + ), + workflow: current, + }), + ).toThrow( + 'beppe_final_research_brief_required_before_ceo_handoff', + ); + + current.artifacts.push({ + id: 'brief-1', + workflowId: 'wf-1', + kind: 'final_research_brief', + createdBy: { + kind: 'agent', + id: 'beppe', + }, + createdAt: + '2026-01-01T00:03:00.000Z', + summary: 'Final brief.', + status: 'active', + metadata: {}, + }); + + const handoffs = + planGovernedHandoffs({ + message: transitionMessage( + 'READY_FOR_FINAL_RESEARCH_SUPERVISOR', + 'WAITING_CEO_RESEARCH_DECISION', + ), + workflow: current, + }); + + expect(handoffs).toHaveLength(1); + + expect( + handoffs[0], + ).toMatchObject({ + kind: + 'ceo_approval_request', + destination: { + kind: 'human', + id: 'ceo', + }, + action: + 'decide_research_proposal', + }); + }); + + test('routes risk analysis to all four mandatory analysts', () => { + const handoffs = + planGovernedHandoffs({ + message: transitionMessage( + 'CEO_RESEARCH_APPROVED', + 'RISK_ANALYSIS', + ), + workflow: workflow( + 'RISK_ANALYSIS', + ), + }); + + expect( + handoffs.map( + (handoff) => + handoff.destination.id, + ), + ).toEqual([ + 'manuel', + 'dimash', + 'bare', + 'angelo', + ]); + }); + + test('never creates an automatic broker execution handoff', () => { + const message: ControlPlaneOutboxMessage = { + messageId: 'financial-1', + topic: + 'control-plane.financial-action.authorized', + partitionKey: 'financial-1', + status: 'pending', + attempts: 0, + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: { + eventId: 'event-financial', + eventType: + 'financial_action_authorized', + financialAction: 'buy', + allowed: true, + }, + }; + + expect( + planGovernedHandoffs({ + message, + }), + ).toEqual([]); + }); + + test('routes denied financial execution to a CEO security alert', () => { + const message: ControlPlaneOutboxMessage = { + messageId: 'financial-denied', + topic: + 'control-plane.financial-action.denied', + partitionKey: + 'financial-denied', + status: 'pending', + attempts: 0, + createdAt: + '2026-01-01T00:00:00.000Z', + availableAt: + '2026-01-01T00:00:00.000Z', + retryPolicy, + payload: { + eventId: + 'event-financial-denied', + eventType: + 'financial_action_denied', + financialAction: 'buy', + allowed: false, + }, + }; + + const handoffs = + planGovernedHandoffs({ + message, + }); + + expect(handoffs).toHaveLength(1); + + expect( + handoffs[0], + ).toMatchObject({ + kind: 'security_alert', + destination: { + kind: 'human', + id: 'ceo', + }, + }); + }); +}); diff --git a/tests/control-plane-handoff-routing.test.ts b/tests/control-plane-handoff-routing.test.ts new file mode 100644 index 00000000..cace46c2 --- /dev/null +++ b/tests/control-plane-handoff-routing.test.ts @@ -0,0 +1,186 @@ +import { + afterEach, + describe, + expect, + test, +} from 'vitest'; + +import { + mkdtempSync, + rmSync, +} from 'node:fs'; + +import { + tmpdir, +} from 'node:os'; + +import path from 'node:path'; + +import { + OutboxConsumerRegistry, +} from '@/lib/control-plane/consumer'; + +import { + GovernedHandoffRouterConsumer, +} from '@/lib/control-plane/handoff-router'; + +import { + ReliableOutboxWorker, +} from '@/lib/control-plane/outbox-worker'; + +import { + SqliteGovernedHandoffStore, +} from '@/lib/control-plane/sqlite-handoff-store'; + +let tempDir: string | null = null; + +afterEach(() => { + if (tempDir) { + rmSync( + tempDir, + { + recursive: true, + force: true, + }, + ); + + tempDir = null; + } +}); + +function store() { + tempDir = mkdtempSync( + path.join( + tmpdir(), + 'startup-handoff-routing-', + ), + ); + + return new SqliteGovernedHandoffStore( + path.join( + tempDir, + 'cp.db', + ), + ); +} + +const retryPolicy = { + maxAttempts: 5, + initialDelayMs: 1_000, + backoffMultiplier: 2, + maxDelayMs: 60_000, + timeoutMs: 30_000, +}; + +describe('Governed handoff routing consumer', () => { + test('turns one transition event into durable agent handoffs idempotently', async () => { + const cp = store(); + + await cp.createWorkflow({ + id: 'wf-1', + state: 'RISK_ANALYSIS', + revision: 1, + createdBy: { + kind: 'agent', + id: 'lauti', + }, + createdAt: + '2026-01-01T00:00:00.000Z', + updatedAt: + '2026-01-01T00:01:00.000Z', + artifacts: [], + invalidations: [], + metadata: {}, + }); + + cp.enqueueOutbox({ + messageId: 'msg-risk', + topic: + 'control-plane.workflow.transitioned', + partitionKey: 'wf-1', + workflowId: 'wf-1', + createdAt: + '2026-01-01T00:01:00.000Z', + availableAt: + '2026-01-01T00:01:00.000Z', + retryPolicy, + payload: { + eventId: 'event-risk', + eventType: + 'workflow_transitioned', + fromState: + 'CEO_RESEARCH_APPROVED', + toState: + 'RISK_ANALYSIS', + }, + }); + + const registry = + new OutboxConsumerRegistry(); + + registry.register( + new GovernedHandoffRouterConsumer( + cp, + ), + ); + + const worker = + new ReliableOutboxWorker( + cp, + registry, + { + workerId: + 'handoff-router-worker', + batchSize: 10, + outboxLeaseMs: 10_000, + consumerLeaseMs: 10_000, + }, + ); + + const first = + await worker.runOnce( + '2026-01-01T00:01:01.000Z', + ); + + expect(first.succeeded).toBe(1); + + expect( + cp.listHandoffs({ + workflowId: 'wf-1', + }).map( + (handoff) => + handoff.destination.id, + ), + ).toEqual([ + 'manuel', + 'dimash', + 'bare', + 'angelo', + ]); + + /* + * Re-plan the same source message directly. Deterministic handoff + * IDs + INSERT OR IGNORE must keep exactly four rows. + */ + const router = + new GovernedHandoffRouterConsumer( + cp, + ); + + await router.handle({ + message: + cp.listOutbox()[0], + idempotencyKey: + 'manual-replay', + deliveryAttempt: 2, + }); + + expect( + cp.listHandoffs({ + workflowId: 'wf-1', + }), + ).toHaveLength(4); + + cp.close(); + }); +}); From 4779b240313cb7ce19b1f623410d09f1c9e583c0 Mon Sep 17 00:00:00 2001 From: pietrozucconi Date: Tue, 22 Sep 2026 13:16:37 +0200 Subject: [PATCH 49/62] Add control plane operator surfaces --- app/approvals/page.tsx | 7 + app/control-plane/page.tsx | 7 + app/layout.tsx | 139 +------- app/tasks/page.tsx | 93 +----- app/workflows/page.tsx | 83 +---- .../default-brain-memory-composer.ts | 280 ++++++++++++++++ lib/control-plane/index.ts | 10 +- .../internal-runtime-adapters.ts | 310 ++++++++++++++++++ lib/control-plane/operator-actions.ts | 18 + lib/control-plane/operator-view.ts | 12 + lib/control-plane/runtime-bootstrap.ts | 47 +++ lib/control-plane/runtime-data.ts | 11 + lib/control-plane/runtime-schema.ts | 37 +++ lib/control-plane/runtime-store.ts | 30 ++ lib/control-plane/sqlite-runtime-store.ts | 65 ++++ lib/nav.ts | 100 +----- tests/control-plane-operator-runtime.test.ts | 13 + tests/nav.test.ts | 2 + tests/smoke.test.ts | 66 +++- 19 files changed, 944 insertions(+), 386 deletions(-) create mode 100644 app/approvals/page.tsx create mode 100644 app/control-plane/page.tsx create mode 100644 lib/control-plane/default-brain-memory-composer.ts create mode 100644 lib/control-plane/internal-runtime-adapters.ts create mode 100644 lib/control-plane/operator-actions.ts create mode 100644 lib/control-plane/operator-view.ts create mode 100644 lib/control-plane/runtime-bootstrap.ts create mode 100644 lib/control-plane/runtime-data.ts create mode 100644 lib/control-plane/runtime-schema.ts create mode 100644 lib/control-plane/runtime-store.ts create mode 100644 lib/control-plane/sqlite-runtime-store.ts create mode 100644 tests/control-plane-operator-runtime.test.ts diff --git a/app/approvals/page.tsx b/app/approvals/page.tsx new file mode 100644 index 00000000..f0483d81 --- /dev/null +++ b/app/approvals/page.tsx @@ -0,0 +1,7 @@ +import { Bell, CheckCircle2, ShieldAlert } from 'lucide-react'; +import { PageHeader } from '@/components/PageHeader'; +import { getControlPlaneRuntimeStore } from '@/lib/control-plane/runtime-data'; +import { acknowledgeCeoInboxAction } from '@/lib/control-plane/operator-actions'; +export const dynamic='force-dynamic'; +const iconFor=(c:string)=>c==='security_alert'?ShieldAlert:c==='approval_request'?CheckCircle2:Bell; +export default function ApprovalsPage(){ const store=getControlPlaneRuntimeStore(); const items=store.listCeoInbox(); const unresolved=items.filter(i=>i.status!=='resolved'); return

Governed approval requests, notifications and security alerts addressed to the human CEO.

Acknowledging only marks an item as seen. Business decisions must still pass through a successful Control Plane command.

{[['Unresolved',unresolved.length],['Approval requests',items.filter(i=>i.category==='approval_request'&&i.status!=='resolved').length],['Security alerts',items.filter(i=>i.category==='security_alert'&&i.status!=='resolved').length]].map(([l,v])=>
{l}
{v}
)}
{items.length===0?
CEO inbox is empty

No human approval request or operator alert yet.

:
{items.map(i=>{const Icon=iconFor(i.category);return
{i.category} · {i.status}
{i.summary}
{i.action}{i.workflowId?` · ${i.workflowId}`:''}
{i.status==='pending'&&
}{i.status!=='resolved'&&i.category==='approval_request'&&
Decision controls are intentionally not exposed yet; they will be wired through the governed Control Plane path.
}
})}
}
; } diff --git a/app/control-plane/page.tsx b/app/control-plane/page.tsx new file mode 100644 index 00000000..c93eafbe --- /dev/null +++ b/app/control-plane/page.tsx @@ -0,0 +1,7 @@ +import { Activity, AlertTriangle, Database, Route } from 'lucide-react'; +import { PageHeader } from '@/components/PageHeader'; +import { getControlPlaneRuntimeStore } from '@/lib/control-plane/runtime-data'; +import { buildControlPlaneOperatorSnapshot } from '@/lib/control-plane/operator-view'; +import { redriveHandoffAction, redriveOutboxAction } from '@/lib/control-plane/operator-actions'; +export const dynamic='force-dynamic'; +export default async function ControlPlanePage(){ const store=getControlPlaneRuntimeStore(); const x=await buildControlPlaneOperatorSnapshot(store); const dh=x.handoffs.filter(h=>h.status==='dead_letter'); const dout=x.outbox.filter(m=>m.status==='dead_letter'); const degraded=x.counts.taskDeadLetters+x.counts.handoffDeadLetters+x.counts.outboxDeadLetters+x.counts.jobDeadLetters>0; return

Operator view over durable workflows, commands, events, outbox delivery, governed handoffs and runtime tasks.

Foundation runtime only: production auth, background workers, PostgreSQL and model-powered agent executors are not connected yet.

Runtime health
{degraded?'Degraded':'Nominal'}
Workflows
{x.counts.workflows}
Pending handoffs
{x.counts.pendingHandoffs}
Dead letters
{x.counts.taskDeadLetters+x.counts.handoffDeadLetters+x.counts.outboxDeadLetters+x.counts.jobDeadLetters}
{[['Commands',x.commands.length],['Domain events',x.events.length],['Consumer receipts',x.consumerReceipts.length],['Audit records',x.audit.length]].map(([l,v])=>
{l}
{v}
)}
{(dh.length>0||dout.length>0)&&
Recovery queue
{dh.map(h=>
Handoff · {h.destination.kind}:{h.destination.id}
{h.handoffId}
)}{dout.map(m=>
Outbox · {m.topic}
{m.messageId}
)}
}
Runtime boundaries
Agent executors: not connected
Production auth: not connected
Broker execution: intentionally disabled
Persistence: SQLite foundation adapter
; } diff --git a/app/layout.tsx b/app/layout.tsx index 4537d713..678359dd 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -1,132 +1,25 @@ import type { Metadata } from 'next'; import { JetBrains_Mono } from 'next/font/google'; import './globals.css'; - import { Sidebar } from '@/components/Sidebar'; import { Topbar } from '@/components/Topbar'; import { CommandPalette } from '@/components/CommandPalette'; import { getDb } from '@/lib/data'; import type { Command } from '@/lib/palette'; import { THEME_INIT_SCRIPT } from '@/lib/theme'; - -const fontMono = JetBrains_Mono({ - subsets: ['latin'], - weight: ['400', '500', '600', '700'], - variable: '--font-mono', -}); - -export const metadata: Metadata = { - title: 'Money Machine', - description: 'AI investment company operating system', -}; - -const NAV_COMMANDS: Command[] = [ - { - id: 'nav-home', - label: 'Home', - keywords: 'dashboard overview company', - href: '/', - hint: 'view', - }, - { - id: 'nav-agents', - label: 'Agents', - keywords: 'agents employees runtime roster', - href: '/agents', - hint: 'view', - }, - { - id: 'nav-tasks', - label: 'Tasks', - keywords: 'tasks work assignments', - href: '/tasks', - hint: 'view', - }, - { - id: 'nav-skills', - label: 'Skills', - keywords: 'skills capabilities', - href: '/skills', - hint: 'view', - }, - { - id: 'nav-org', - label: 'Org Chart', - keywords: 'organization hierarchy departments teams', - href: '/org', - hint: 'view', - }, - { - id: 'nav-brain', - label: 'Startup Brain', - keywords: 'brain memory knowledge experience decisions lessons', - href: '/brain', - hint: 'view', - }, - { - id: 'nav-connections', - label: 'Connections', - keywords: 'integrations tools data sources', - href: '/integrations', - hint: 'view', - }, - { - id: 'nav-analytics', - label: 'Analytics', - keywords: 'analytics metrics performance kpi', - href: '/analytics', - hint: 'view', - }, -]; - -function buildCommands(): Command[] { - const db = getDb(); - - const agents: Command[] = db.agents.all().map((agent) => ({ - id: `agent-${agent.id}`, - label: agent.name, - keywords: `${agent.role} ${agent.description}`, - href: '/agents', - hint: 'agent', - })); - - return [...NAV_COMMANDS, ...agents]; -} - -export default function RootLayout({ - children, -}: { - children: React.ReactNode; -}) { - return ( - - -