Struct PlanningEngine 

pub struct PlanningEngine { /* private fields */ }

Implementations

impl PlanningEngine

pub fn open(path: impl AsRef<Path>) -> Result<Self>

pub fn create(path: impl AsRef<Path>) -> Result<Self>

pub fn load(path: impl AsRef<Path>) -> Result<Self>

pub fn save(&mut self) -> Result<()>

impl PlanningEngine

pub fn calculate_singularity_parallel(&self) -> IntentionSingularity

Compute the intention singularity with pre-filtered active goals.

Optimization over raw get_intention_singularity():

• Pre-collects active goal references to avoid repeated status checks
• Short-circuits the empty case (no active goals → empty singularity)

pub fn scan_blockers_parallel(&self) -> Vec<BlockerProphecy>

Scan for blocker prophecies with pre-filtered active goals.

Optimization: pre-computes blocker type frequency histogram once, then runs prediction in a single pass with pre-allocated output.

pub fn progress_echoes_parallel(&self) -> Vec<ProgressEcho>

Detect progress echoes with pre-filtered near-completion goals.

Optimization: only examines goals with progress > 0.5 and momentum > 0.2, skipping the bulk of low-progress goals. Uses the same logic as listen_progress_echoes but with an early-exit filter.

pub fn create_goals_batch( &mut self, requests: Vec<CreateGoalRequest>, ) -> Result<Vec<Goal>>

Create multiple goals in a single batch operation.

Unlike calling create_goal() N times, this:

1. Validates ALL requests upfront (fail-fast: no partial inserts on error)
2. Pre-generates IDs and timestamps in one pass
3. Inserts all goals into the store
4. Wires parent/child and dependency links
5. Rebuilds indexes ONCE at the end (not N incremental adds)

Performance: for N=10 goals, avoids 9 redundant index rebuilds. For N=100, the savings are substantial.

pub fn batch_activate_goals(&mut self, ids: &[GoalId]) -> Result<Vec<Goal>>

Activate multiple Draft/Reborn goals in one pass.

Validates all IDs upfront (fail-fast), applies transitions, and calls mark_dirty once at the end.

pub fn batch_progress_goals( &mut self, updates: Vec<(GoalId, f64, Option<String>)>, ) -> Result<Vec<Goal>>

Progress multiple goals at once with batched velocity/momentum recalc.

Each entry is (goal_id, new_percentage, optional_note). Validates all IDs upfront, records progress points, recalculates velocity/momentum/confidence for each, and marks dirty once.

pub fn batch_create_decisions( &mut self, requests: Vec<CreateDecisionRequest>, ) -> Result<Vec<Decision>>

Create multiple decisions in a single batch.

Validates all requests upfront, generates IDs, wires goal links and causal chains, rebuilds indexes once.

pub fn batch_create_commitments( &mut self, requests: Vec<CreateCommitmentRequest>, ) -> Result<Vec<Commitment>>

Create multiple commitments in a single batch.

Validates all requests, generates IDs, calculates weight/inertia/cost for each, wires to goals, and marks dirty once.

pub fn batch_fulfill_commitments( &mut self, fulfillments: Vec<(CommitmentId, String)>, ) -> Result<Vec<Commitment>>

Fulfill multiple commitments in a single pass.

Validates all are Active upfront, calculates chain bonuses, applies fulfillments, and handles entanglement energy release.

pub fn momentum_report_indexed(&self) -> MomentumReport

Momentum report with pre-filtered index-based active goals.

Optimization over get_momentum_report():

• Uses indexes.goals_by_status to avoid full store scan
• Same output shape, but skips inactive/completed goals entirely

pub fn gravity_field_indexed(&self) -> GravityField

Gravity field with index-based pre-filtering.

Optimization over get_gravity_field():

• Uses indexes.goals_by_status to skip inactive goals
• Computes weighted center and gravity wells in a single pass

pub fn at_risk_commitments_scan(&self) -> Vec<(CommitmentId, Vec<String>)>

Scan all active commitments for at-risk status in one pass.

Returns commitment IDs and their risk signals.

pub fn metamorphosis_scan(&self) -> Vec<MetamorphosisSignal>

Scan all active/blocked goals for metamorphosis signals in one pass.

Returns only goals that should transform, skipping stable ones.

pub fn progress_forecast_batch(&self, ids: &[GoalId]) -> Vec<ProgressForecast>

Progress forecasts for multiple goals at once.

Collects forecasts for all specified goals, returning partial results (skipping not-found goals rather than failing).

pub fn progress_forecast_all_active(&self) -> Vec<ProgressForecast>

Progress forecasts for ALL active goals.

Uses index to identify active goals, then computes forecasts in a single pass. Useful for dashboard views.

pub fn dream_goals_batch(&mut self, ids: &[GoalId]) -> Vec<Result<Dream>>

Dream multiple goals and collect all resulting dreams.

Unlike calling dream_goal N times, this batches the dirty marking. Note: each dream may create child goals if confidence > 0.7.

pub fn federation_health_scan(&self) -> Vec<FederationHealthEntry>

Check health across all federations in one pass.

Returns federation ID, member count, sync freshness, and any issues.

pub fn goal_health_scan(&self) -> GoalHealthReport

Comprehensive health scan across all active goals.

Single-pass check for: stalled goals, neglected goals, goals nearing deadline, blocked goals, and high-momentum goals (opportunities).

pub fn start_consensus( &mut self, decision_id: DecisionId, participants: Vec<ConsensusParticipant>, ) -> Result<DecisionConsensus>

Start a consensus process for a decision with multiple stakeholders.

Validates the decision exists and is in Pending or Deliberating status. Creates a DecisionConsensus record and transitions the decision to Deliberating.

pub fn add_deliberation_round( &mut self, decision_id: DecisionId, statements: Vec<ConsensusStatement>, common_ground: Vec<CommonGround>, ) -> Result<DecisionConsensus>

Add a deliberation round to an active consensus process.

Each round collects statements from stakeholders and identifies common ground. The alignment score is recalculated after each round.

pub fn synthesize_consensus( &mut self, decision_id: DecisionId, proposal: String, incorporates_from: Vec<StakeholderId>, addresses_concerns: Vec<String>, ) -> Result<DecisionConsensus>

Propose a synthesis that attempts to reconcile stakeholder positions.

pub fn record_consensus_vote( &mut self, decision_id: DecisionId, stakeholder_id: StakeholderId, vote: String, ) -> Result<DecisionConsensus>

Record a stakeholder’s vote on the current synthesis.

pub fn get_consensus_status( &self, decision_id: DecisionId, ) -> Result<&DecisionConsensus>

Get the current status of a consensus process.

pub fn crystallize_consensus( &mut self, decision_id: DecisionId, chosen_path: PathId, force: bool, ) -> Result<DecisionConsensus>

Crystallize a consensus decision once alignment is sufficient.

If alignment_score >= 0.5 (or force=true), crystallizes the decision and records the consensus outcome. Otherwise returns Deadlocked.

impl PlanningEngine

pub fn get_goal(&self, id: GoalId) -> Option<&Goal>

pub fn list_goals(&self, filter: GoalFilter) -> Vec<&Goal>

pub fn get_root_goals(&self) -> Vec<&Goal>

pub fn get_active_goals(&self) -> Vec<&Goal>

pub fn get_blocked_goals(&self) -> Vec<&Goal>

pub fn get_urgent_goals(&self, within_days: f64) -> Vec<&Goal>

pub fn get_goal_tree(&self, root_id: GoalId) -> Option<GoalTree>

pub fn search_goals(&self, query: &str) -> Vec<&Goal>

pub fn get_intention_singularity(&self) -> IntentionSingularity

pub fn get_decision(&self, id: DecisionId) -> Option<&Decision>

pub fn get_decision_chain(&self, id: DecisionId) -> Option<DecisionChain>

pub fn get_shadows(&self, id: DecisionId) -> Vec<&CrystalShadow>

pub fn project_counterfactual( &self, decision_id: DecisionId, path_id: PathId, ) -> Option<CounterfactualProjection>

pub fn decision_archaeology(&self, artifact: &str) -> DecisionArchaeology

pub fn get_commitment(&self, id: CommitmentId) -> Option<&Commitment>

pub fn get_dream(&self, id: DreamId) -> Option<&Dream>

pub fn list_dreams(&self) -> Vec<&Dream>

pub fn list_goal_dreams(&self, goal_id: GoalId) -> Vec<&Dream>

pub fn list_decisions(&self) -> Vec<&Decision>

pub fn list_commitments(&self) -> Vec<&Commitment>

pub fn get_due_soon(&self, within_days: f64) -> Vec<&Commitment>

pub fn get_commitment_inventory(&self) -> CommitmentInventory

pub fn get_at_risk_commitments(&self) -> Vec<&Commitment>

pub fn get_federation(&self, id: FederationId) -> Option<&Federation>

pub fn list_federations(&self) -> Vec<&Federation>

pub fn get_federation_members( &self, id: FederationId, ) -> Option<Vec<FederationMember>>

pub fn scan_blocker_prophecy(&self) -> Vec<BlockerProphecy>

pub fn listen_progress_echoes(&self) -> Vec<ProgressEcho>

pub fn get_decision_prophecy( &self, question: &str, options: &[DecisionPath], ) -> DecisionProphecy

pub fn search_decisions(&self, query: &str) -> Vec<Decision>

pub fn get_progress_forecast(&self, id: GoalId) -> Result<ProgressForecast>

pub fn get_momentum_report(&self) -> MomentumReport

pub fn get_gravity_field(&self) -> GravityField

impl PlanningEngine

pub fn validate_create_goal( &self, request: &CreateGoalRequest, ) -> ValidationResult<()>

pub fn validate_status_transition( &self, current: GoalStatus, target: GoalStatus, ) -> ValidationResult<()>

pub fn validate_create_decision( &self, request: &CreateDecisionRequest, ) -> ValidationResult<()>

pub fn validate_crystallize(&self, decision: &Decision) -> ValidationResult<()>

pub fn validate_no_self_dependency( &self, goal_id: GoalId, dependencies: &[GoalId], ) -> ValidationResult<()>

R4: Validate that a goal does not depend on itself

pub fn validate_create_dream( &self, scenarios_count: usize, ) -> ValidationResult<()>

R4: Validate dream creation — at least 1 scenario required

pub fn validate_create_federation( &self, member_count: usize, ) -> ValidationResult<()>

R4: Validate federation creation — at least 2 members required

pub fn validate_create_commitment( &self, request: &CreateCommitmentRequest, ) -> ValidationResult<()>

impl PlanningEngine

pub fn create_goal(&mut self, request: CreateGoalRequest) -> Result<Goal>

pub fn activate_goal(&mut self, id: GoalId) -> Result<Goal>

pub fn pause_goal(&mut self, id: GoalId, reason: Option<String>) -> Result<Goal>

pub fn resume_goal(&mut self, id: GoalId) -> Result<Goal>

pub fn progress_goal( &mut self, id: GoalId, percentage: f64, note: Option<String>, ) -> Result<Goal>

pub fn complete_goal( &mut self, id: GoalId, note: Option<String>, ) -> Result<Goal>

pub fn abandon_goal(&mut self, id: GoalId, reason: String) -> Result<Goal>

pub fn reincarnate_goal( &mut self, original_id: GoalId, updates: ReincarnationUpdates, ) -> Result<Goal>

pub fn decompose_goal( &mut self, id: GoalId, sub_goals: Vec<CreateGoalRequest>, ) -> Result<Vec<Goal>>

pub fn block_goal(&mut self, id: GoalId, blocker: Blocker) -> Result<Goal>

pub fn unblock_goal( &mut self, id: GoalId, blocker_id: Uuid, resolution: String, ) -> Result<Goal>

pub fn link_goals(&mut self, relationship: GoalRelationship) -> Result<()>

pub fn create_decision( &mut self, request: CreateDecisionRequest, ) -> Result<Decision>

pub fn add_option( &mut self, id: DecisionId, path: DecisionPath, ) -> Result<Decision>

pub fn crystallize( &mut self, id: DecisionId, chosen_path_id: PathId, reasoning: DecisionReasoning, ) -> Result<Decision>

pub fn record_consequence( &mut self, id: DecisionId, consequence: Consequence, ) -> Result<Decision>

pub fn recrystallize( &mut self, id: DecisionId, new_path_id: PathId, reason: String, ) -> Result<Decision>

pub fn create_commitment( &mut self, request: CreateCommitmentRequest, ) -> Result<Commitment>

pub fn fulfill_commitment( &mut self, id: CommitmentId, how_delivered: String, ) -> Result<Commitment>

pub fn break_commitment( &mut self, id: CommitmentId, reason: String, ) -> Result<Commitment>

pub fn renegotiate_commitment( &mut self, id: CommitmentId, new_promise: Promise, reason: String, ) -> Result<Commitment>

pub fn entangle_commitments( &mut self, a: CommitmentId, b: CommitmentId, entanglement_type: EntanglementType, strength: f64, ) -> Result<()>

pub fn dream_goal(&mut self, id: GoalId) -> Result<Dream>

pub fn create_federation( &mut self, goal_id: GoalId, agent_id: String, coordinator: Option<String>, ) -> Result<Federation>

pub fn join_federation( &mut self, federation_id: FederationId, agent_id: String, ) -> Result<Federation>

pub fn sync_federation( &mut self, federation_id: FederationId, ) -> Result<Federation>

pub fn handoff_federation( &mut self, federation_id: FederationId, next_coordinator: String, ) -> Result<Federation>

pub fn detect_metamorphosis( &self, goal_id: GoalId, ) -> Result<MetamorphosisSignal>

pub fn approve_metamorphosis( &mut self, goal_id: GoalId, stage_title: String, stage_description: String, change: ScopeChange, ) -> Result<Goal>

pub fn metamorphosis_history( &self, goal_id: GoalId, ) -> Result<Vec<MetamorphicStage>>

pub fn predict_metamorphosis( &self, goal_id: GoalId, ) -> Result<MetamorphosisPrediction>

pub fn metamorphosis_stage( &self, goal_id: GoalId, ) -> Result<Option<MetamorphicStage>>

pub fn merge_from(&mut self, source: &PlanningEngine) -> MergeReport

pub fn update_goal( &mut self, id: GoalId, updates: UpdateGoalRequest, ) -> Result<Goal>

pub fn update_regret(&mut self, id: DecisionId) -> Result<Decision>

pub fn record_insight( &mut self, dream_id: DreamId, insight: DreamInsight, ) -> Result<Dream>

pub fn assess_accuracy( &mut self, dream_id: DreamId, accuracy: DreamAccuracy, ) -> Result<Dream>

pub fn update_momentum(&mut self, id: GoalId) -> Result<Goal>

pub fn update_gravity(&mut self, id: GoalId) -> Result<Goal>

pub fn update_feelings(&mut self, id: GoalId) -> Result<Goal>

pub fn update_commitment( &mut self, id: CommitmentId, updates: UpdateCommitmentRequest, ) -> Result<Commitment>

pub fn validate(&self) -> Vec<String>

impl PlanningEngine

pub fn in_memory() -> Self

pub fn goal_count(&self) -> usize

pub fn decision_count(&self) -> usize

pub fn commitment_count(&self) -> usize

pub fn session_id(&self) -> Uuid

pub fn audit_log_mut(&mut self) -> &mut AuditLog

pub fn goals(&self) -> impl Iterator<Item = &Goal>

Iterate over all goals (for ghost bridge context).

pub fn decisions(&self) -> impl Iterator<Item = &Decision>

Iterate over all decisions (for ghost bridge context).

pub fn commitments(&self) -> impl Iterator<Item = &Commitment>

Iterate over all commitments (for ghost bridge context).

Trait Implementations

impl Clone for PlanningEngine

fn clone(&self) -> PlanningEngine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PlanningEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.