pulseed 0.4.18 → 0.4.19

package/dist/orchestrator/strategy/portfolio-allocation.js

@@ -0,0 +1,265 @@
+// ─── Helpers ───
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+// ─── Resource Allocation ───
+/**
+ * Allocate resource shares across goals based on their priority scores.
+ *
+ * Rules:
+ *   1. If goals > max_concurrent_goals, lowest priority goals get allocation=0
+ *      and are labelled "waiting".
+ *   2. Active goals (up to max_concurrent_goals) share 1.0 proportionally to
+ *      computed_priority, with a floor of min_goal_share.
+ *   3. Sum of active allocations = 1.0.
+ *
+ * @param priorities — output from calculateGoalPriorities
+ * @param config — allocation configuration (max_concurrent_goals, min_goal_share)
+ * @param strategy   — optional AllocationStrategy (default: 'priority')
+ * @param momentumMap — goalId → MomentumInfo, required when strategy.type === 'momentum'
+ * @param depSchedule — DependencySchedule, required when strategy.type === 'dependency_aware'
+ * @returns CrossGoalAllocation[] in the same order as priorities
+ */
+export function allocateResources(priorities, config, strategy, momentumMap, depSchedule) {
+    if (priorities.length === 0)
+        return [];
+    const { max_concurrent_goals, min_goal_share } = config;
+    // Split into active (top N) and waiting (rest), already sorted desc
+    const activeCount = Math.min(priorities.length, max_concurrent_goals);
+    const activePriorities = priorities.slice(0, activeCount);
+    const waitingPriorities = priorities.slice(activeCount);
+    // Build allocations for waiting goals (zero share)
+    const waitingAllocations = waitingPriorities.map((p) => ({
+        goal_id: p.goal_id,
+        priority: p.computed_priority,
+        resource_share: 0,
+        adjustment_reason: `waiting: exceeds max_concurrent_goals (${max_concurrent_goals})`,
+    }));
+    if (activePriorities.length === 0)
+        return waitingAllocations;
+    // Single goal gets everything
+    if (activePriorities.length === 1) {
+        return [
+            {
+                goal_id: activePriorities[0]?.goal_id ?? "",
+                priority: activePriorities[0]?.computed_priority ?? 0,
+                resource_share: 1.0,
+                adjustment_reason: "sole active goal",
+            },
+            ...waitingAllocations,
+        ];
+    }
+    const n = activePriorities.length;
+    // --- Strategy-specific weight computation ---
+    const strategyType = strategy?.type ?? "priority";
+    let weights;
+    let strategyReason;
+    if (strategyType === "equal") {
+        weights = activePriorities.map(() => 1);
+        strategyReason = "equal allocation";
+    }
+    else if (strategyType === "momentum" && momentumMap && momentumMap.size > 0) {
+        const momentumWeight = strategy?.momentumWeight ?? 0.5;
+        // Blend priority and momentum velocity
+        weights = activePriorities.map((p) => {
+            const mom = momentumMap.get(p.goal_id);
+            const vel = mom ? Math.max(mom.velocity, 0) : 0;
+            return (1 - momentumWeight) * p.computed_priority + momentumWeight * vel;
+        });
+        strategyReason = "momentum-weighted";
+    }
+    else if (strategyType === "dependency_aware" && depSchedule) {
+        // Goals on critical path and unblocked goals get a boost
+        const criticalSet = new Set(depSchedule.criticalPath);
+        // Determine which goals are currently unblocked (in phase 0 or phase whose blockedBy are empty)
+        const unblockedGoals = new Set();
+        for (const phase of depSchedule.phases) {
+            if (phase.blockedBy.length === 0) {
+                for (const id of phase.goalIds)
+                    unblockedGoals.add(id);
+            }
+        }
+        weights = activePriorities.map((p) => {
+            let w = p.computed_priority;
+            if (criticalSet.has(p.goal_id))
+                w *= 1.5;
+            if (unblockedGoals.has(p.goal_id))
+                w *= 1.2;
+            return w;
+        });
+        strategyReason = "dependency_aware";
+    }
+    else {
+        // Default: priority-proportional
+        weights = activePriorities.map((p) => p.computed_priority);
+        strategyReason = "priority";
+    }
+    // Proportional allocation with guaranteed min_goal_share floor.
+    //
+    // Algorithm:
+    //   1. Reserve min_goal_share for every active goal.
+    //   2. Distribute the remaining budget (1 - n * min_goal_share) proportionally
+    //      by computed weight.
+    //   3. This guarantees every active goal has at least min_goal_share.
+    //
+    // Edge case: if n * min_goal_share >= 1 (too many goals for the floor to
+    // allow proportional distribution), fall back to equal distribution.
+    const reservedTotal = n * min_goal_share;
+    let finalShares;
+    if (reservedTotal >= 1) {
+        // No room for proportional top-up — give everyone an equal share
+        finalShares = activePriorities.map(() => 1 / n);
+    }
+    else {
+        const remainingBudget = 1 - reservedTotal;
+        const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+        if (totalWeight === 0) {
+            // All zero — split remaining budget equally
+            finalShares = activePriorities.map(() => min_goal_share + remainingBudget / n);
+        }
+        else {
+            finalShares = weights.map((w) => min_goal_share + remainingBudget * (w / totalWeight));
+        }
+    }
+    // Track which goals received the floor for reason strings
+    const totalWeightForReason = weights.reduce((sum, w) => sum + w, 0);
+    const rawShares = totalWeightForReason === 0
+        ? activePriorities.map(() => 1 / n)
+        : weights.map((w) => w / totalWeightForReason);
+    const activeAllocations = activePriorities.map((p, i) => {
+        const share = finalShares[i];
+        const raw = rawShares[i];
+        let reason;
+        if (raw < min_goal_share) {
+            reason = `min_goal_share floor applied (raw=${raw.toFixed(3)}, strategy=${strategyReason})`;
+        }
+        else {
+            reason = `${strategyReason}: weight=${(weights[i] ?? 0).toFixed(3)}`;
+        }
+        return {
+            goal_id: p.goal_id,
+            priority: p.computed_priority,
+            resource_share: share,
+            adjustment_reason: reason,
+        };
+    });
+    return [...activeAllocations, ...waitingAllocations];
+}
+// ─── Stall Rebalancing ───
+/**
+ * Detect stalled goals and redistribute their resources to progressing goals.
+ *
+ * A goal is considered stalled if its MomentumInfo.trend === 'stalled'.
+ * Resources from stalled goals are redistributed proportionally to
+ * non-stalled goals based on their velocity.
+ *
+ * @param currentAllocations — current CrossGoalAllocation array
+ * @param momentumMap — goalId → MomentumInfo
+ * @returns array of RebalanceActions taken (empty if no stalled goals)
+ */
+export function rebalanceOnStall(currentAllocations, momentumMap) {
+    const actions = [];
+    if (currentAllocations.length === 0)
+        return actions;
+    const stalled = [];
+    const progressing = [];
+    for (const alloc of currentAllocations) {
+        const mom = momentumMap.get(alloc.goal_id);
+        if (!mom)
+            continue; // unknown momentum — keep current allocation
+        if (mom.trend === "stalled") {
+            stalled.push(alloc);
+        }
+        else {
+            progressing.push(alloc);
+        }
+    }
+    if (stalled.length === 0)
+        return actions;
+    // Nothing to redistribute to
+    if (progressing.length === 0)
+        return actions;
+    // Calculate total share to redistribute
+    const redistributeTotal = stalled.reduce((s, a) => s + a.resource_share, 0);
+    // Compute target shares for progressing goals, weighted by velocity
+    const totalVelocity = progressing.reduce((s, a) => {
+        const mom = momentumMap.get(a.goal_id);
+        return s + Math.max(mom?.velocity ?? 0, 0);
+    }, 0);
+    for (const alloc of stalled) {
+        actions.push({
+            goalId: alloc.goal_id,
+            action: "reduce",
+            reason: "stalled: momentum velocity ≈ 0",
+            previousShare: alloc.resource_share,
+            newShare: 0,
+        });
+    }
+    for (const alloc of progressing) {
+        const mom = momentumMap.get(alloc.goal_id);
+        const vel = Math.max(mom?.velocity ?? 0, 0);
+        const bonus = totalVelocity > 0
+            ? redistributeTotal * (vel / totalVelocity)
+            : redistributeTotal / progressing.length;
+        const newShare = clamp(alloc.resource_share + bonus, 0, 1);
+        actions.push({
+            goalId: alloc.goal_id,
+            action: "increase",
+            reason: `received share from stalled goals (velocity=${vel.toFixed(4)})`,
+            previousShare: alloc.resource_share,
+            newShare,
+        });
+    }
+    return actions;
+}
+// ─── Strategy Helpers ───
+/**
+ * Check if a strategy is a WaitStrategy (has wait-specific fields).
+ * Pure function — no class dependency.
+ */
+export function isWaitStrategy(strategy) {
+    const s = strategy;
+    return (typeof s["wait_reason"] === "string" &&
+        typeof s["wait_until"] === "string" &&
+        typeof s["measurement_plan"] === "string");
+}
+/**
+ * Check whether a strategy should be terminated.
+ *
+ * Three conditions (design doc sec 6.4):
+ * 1. Lowest effectiveness score for 3 consecutive rebalances at min allocation
+ * 2. consecutive_stall_count >= 3
+ * 3. Resource consumption > 2x estimate
+ */
+export function checkStrategyTermination(strategy, records, config, rebalanceHistory, countConsecutiveLowest) {
+    if (strategy.consecutive_stall_count >= config.termination_stall_count) {
+        return true;
+    }
+    const sessionsConsumed = strategy.tasks_generated.length;
+    const estimatedSessions = strategy.resource_estimate.sessions;
+    if (estimatedSessions > 0 &&
+        sessionsConsumed > estimatedSessions * config.termination_resource_multiplier) {
+        return true;
+    }
+    if (strategy.allocation <= config.min_allocation) {
+        const record = records.find((r) => r.strategy_id === strategy.id);
+        if (record?.effectiveness_score !== null && record !== undefined) {
+            const otherScores = records
+                .filter((r) => r.strategy_id !== strategy.id &&
+                r.effectiveness_score !== null)
+                .map((r) => r.effectiveness_score);
+            if (otherScores.length > 0) {
+                const isLowest = otherScores.every((s) => s >= record.effectiveness_score);
+                if (isLowest) {
+                    const history = rebalanceHistory.get(strategy.goal_id) ?? [];
+                    const recentCount = countConsecutiveLowest(strategy.id, history, config.min_allocation);
+                    if (recentCount >= config.termination_min_rebalances) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=portfolio-allocation.js.map

package/dist/orchestrator/strategy/portfolio-allocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portfolio-allocation.js","sourceRoot":"","sources":["../../../src/orchestrator/strategy/portfolio-allocation.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/strategy/portfolio-manager.d.ts

@@ -0,0 +1,147 @@
+import { StrategyManager } from "./strategy-manager.js";
+import { StateManager } from "../../base/state/state-manager.js";
+import type { Strategy } from "../../base/types/strategy.js";
+import type { PortfolioConfig, EffectivenessRecord, TaskSelectionResult, RebalanceTrigger, RebalanceResult } from "../../base/types/portfolio.js";
+/**
+ * PortfolioManager provides portfolio-level orchestration on top of StrategyManager.
+ *
+ * Responsibilities:
+ * - Deterministic task-strategy selection (which strategy should generate the next task)
+ * - Effectiveness measurement per strategy (gap delta / sessions consumed)
+ * - Rebalance triggering and execution (allocation adjustment, termination)
+ * - Wait-strategy lifecycle management
+ *
+ * PortfolioManager does NOT replace StrategyManager — it coordinates across strategies.
+ */
+export declare class PortfolioManager {
+    private readonly strategyManager;
+    private readonly stateManager;
+    private readonly config;
+    /** goalId → timestamp of last rebalance */
+    private readonly lastRebalanceTime;
+    /** goalId → list of past rebalance results */
+    private readonly rebalanceHistory;
+    /** strategyId → timestamp of last task completion */
+    private readonly lastTaskCompletionByStrategy;
+    constructor(strategyManager: StrategyManager, stateManager: StateManager, config?: Partial<PortfolioConfig>);
+    /**
+     * Select the next strategy that should generate a task for the given goal.
+     *
+     * Uses a deterministic "wait ratio" approach: for each active strategy,
+     * compute (time since last task completion) / allocation. The strategy
+     * with the highest ratio is the most "starved" and gets selected next.
+     *
+     * WaitStrategy instances are skipped (they do not generate tasks).
+     * Returns null if no eligible active strategies exist.
+     */
+    selectNextStrategyForTask(goalId: string): Promise<TaskSelectionResult | null>;
+    /**
+     * Calculate effectiveness records for all active strategies of a goal.
+     *
+     * effectiveness_score = gap_delta_attributed / sessions_consumed
+     *
+     * Uses dimension-target matching (method 2): sum gap changes in each
+     * strategy's target_dimensions and attribute them to that strategy.
+     *
+     * Requires a minimum number of task completions (default 3) before
+     * producing a non-null score.
+     */
+    calculateEffectiveness(goalId: string): Promise<EffectivenessRecord[]>;
+    /**
+     * Check whether a rebalance is needed for the given goal.
+     *
+     * Two trigger types:
+     * - periodic: rebalance_interval has elapsed since last rebalance
+     * - score_change: any effectiveness_score changed 50%+ since last rebalance
+     *
+     * Returns the trigger or null.
+     */
+    shouldRebalance(goalId: string): Promise<RebalanceTrigger | null>;
+    /**
+     * Execute a rebalance for the given goal based on the trigger.
+     *
+     * Logic (design doc sec 6.3):
+     * - All scores null: no change
+     * - Score ratio < 2.0: no change
+     * - Score ratio >= 2.0: increase high-performer allocation, decrease low-performer
+     *   (respect min 0.1)
+     * - Check termination conditions and terminate if met
+     * - If all terminated: set new_generation_needed = true
+     * - Redistribute terminated strategy allocation proportionally
+     */
+    rebalance(goalId: string, trigger: RebalanceTrigger): Promise<RebalanceResult>;
+    /**
+     * Check whether a strategy should be terminated.
+     *
+     * Three conditions (design doc sec 6.4):
+     * 1. Lowest effectiveness score for 3 consecutive rebalances at min allocation
+     * 2. consecutive_stall_count >= 3
+     * 3. Resource consumption > 2x estimate
+     */
+    checkTermination(strategy: Strategy, records: EffectivenessRecord[]): boolean;
+    /**
+     * Activate multiple strategies with initial allocation.
+     *
+     * Single strategy: allocation = 1.0
+     * Multiple: equal split as default, respecting min 0.1 and max 0.7, sum = 1.0
+     */
+    activateStrategies(goalId: string, strategyIds: string[]): void;
+    /**
+     * Check if a strategy is a WaitStrategy (has wait-specific fields).
+     */
+    isWaitStrategy(strategy: Strategy): boolean;
+    /**
+     * Handle expiry of a WaitStrategy.
+     *
+     * When wait_until has passed:
+     * - Gap improved: complete the WaitStrategy
+     * - Gap unchanged: activate fallback strategy if one exists, otherwise trigger rebalance
+     * - Gap worsened: terminate the WaitStrategy and trigger rebalance
+     */
+    handleWaitStrategyExpiry(goalId: string, strategyId: string): Promise<RebalanceTrigger | null>;
+    /**
+     * Record a task completion timestamp for a strategy.
+     * Called externally when a task finishes execution.
+     */
+    recordTaskCompletion(strategyId: string): void;
+    /**
+     * Get the rebalance history for a goal.
+     */
+    getRebalanceHistory(goalId: string): RebalanceResult[];
+    /**
+     * Select the next strategy to execute across multiple goals.
+     *
+     * Uses CrossGoalPortfolio's allocation to determine which goal gets the
+     * next turn (most underserved relative to its allocation), then selects
+     * a strategy within that goal using selectNextStrategyForTask().
+     *
+     * Returns null if no strategies are available across all goals.
+     */
+    selectNextStrategyAcrossGoals(goalIds: string[], goalAllocations: Map<string, number>): Promise<{
+        goal_id: string;
+        strategy_id: string | null;
+        selection_reason: string;
+    } | null>;
+    /**
+     * Track how many tasks have been dispatched per goal.
+     * Updated via recordGoalTaskDispatched().
+     */
+    readonly goalTaskCounts: Map<string, number>;
+    /**
+     * Record that a task was dispatched for the given goal.
+     * Used by selectNextStrategyAcrossGoals() to track saturation.
+     */
+    recordGoalTaskDispatched(goalId: string): void;
+    private calculateGapDeltaForStrategy;
+    private getCurrentGapForDimension;
+    /**
+     * Update a single strategy's allocation in the portfolio.
+     * Reads portfolio, modifies the strategy, and writes back.
+     */
+    private updateStrategyAllocation;
+    /**
+     * Record a rebalance result and update tracking state.
+     */
+    private recordRebalance;
+}
+//# sourceMappingURL=portfolio-manager.d.ts.map

package/dist/orchestrator/strategy/portfolio-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portfolio-manager.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/strategy/portfolio-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEjE,OAAO,KAAK,EAAE,QAAQ,EAAa,MAAM,8BAA8B,CAAC;AAGxE,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EAChB,MAAM,+BAA+B,CAAC;AAgBvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAkC;IAEpE,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CACrB;IAEZ,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CACjC;gBAGV,eAAe,EAAE,eAAe,EAChC,YAAY,EAAE,YAAY,EAC1B,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IASnC;;;;;;;;;OASG;IACG,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IA6CpF;;;;;;;;;;OAUG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAiC5E;;;;;;;;OAQG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAiDvE;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAwFpF;;;;;;;OAOG;IACH,gBAAgB,CACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,mBAAmB,EAAE,GAC7B,OAAO;IAUV;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI;IAe/D;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAI3C;;;;;;;OAOG;IACG,wBAAwB,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAkBnC;;;OAGG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAI9C;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAItD;;;;;;;;OAQG;IACG,6BAA6B,CACjC,OAAO,EAAE,MAAM,EAAE,EACjB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GAAG,IAAI,CAAC;IAST;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAa;IAEzD;;;OAGG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;YAMhC,4BAA4B;YAQ5B,yBAAyB;IAQvC;;;OAGG;YACW,wBAAwB;IAoBtC;;OAEG;YACW,eAAe;CAY9B"}