conatus 0.1.0

package/dist/cross-goal-portfolio.d.ts

@@ -0,0 +1,153 @@
+import { StateManager } from "./state-manager.js";
+import { GoalDependencyGraph } from "./goal-dependency-graph.js";
+import { VectorIndex } from "./vector-index.js";
+import type { IEmbeddingClient } from "./embedding-client.js";
+import type { CrossGoalAllocation, CrossGoalPortfolioConfig, GoalPriorityFactors, StrategyTemplate, CrossGoalRebalanceResult, CrossGoalRebalanceTrigger, MomentumInfo, DependencySchedule, AllocationStrategy, RebalanceAction } from "./types/cross-portfolio.js";
+/**
+ * CrossGoalPortfolio manages resource allocation and priority across multiple
+ * active goals. It sits above individual PortfolioManager instances and answers
+ * the question: "given N active goals, how should overall resources be split?"
+ *
+ * Responsibilities:
+ *   - Calculate per-goal priority scores from 4 factors
+ *   - Allocate resource shares proportionally
+ *   - Rebalance on 4 trigger types
+ *   - Recommend strategy templates using vector similarity
+ *
+ * CrossGoalPortfolio does NOT manage strategies within a single goal —
+ * that remains the responsibility of PortfolioManager.
+ */
+export declare class CrossGoalPortfolio {
+    private readonly stateManager;
+    private readonly goalDependencyGraph;
+    private readonly vectorIndex;
+    private readonly embeddingClient;
+    private readonly config;
+    /** goalId → cached GoalPriorityFactors from the last calculation */
+    private lastPriorities;
+    constructor(stateManager: StateManager, goalDependencyGraph: GoalDependencyGraph, vectorIndex: VectorIndex, embeddingClient: IEmbeddingClient, config?: Partial<CrossGoalPortfolioConfig>);
+    /**
+     * Calculate priority factors for each goal in the provided list.
+     *
+     * The 4 factors and their weights:
+     *   w1=0.35  deadline_urgency    — how soon the goal must be finished
+     *   w2=0.25  gap_severity        — worst-case normalized gap across dimensions
+     *   w3=0.25  dependency_weight   — how many goals depend on this one
+     *   w4=0.15  user_priority       — user-specified priority (1-5 → 0-1)
+     *
+     * After the weighted sum is computed, synergy/conflict edges from
+     * GoalDependencyGraph adjust the final score before clamping to [0,1].
+     *
+     * @param goalIds — IDs of goals to evaluate (missing goals are skipped)
+     * @returns GoalPriorityFactors[] sorted by computed_priority descending
+     */
+    calculateGoalPriorities(goalIds: string[]): GoalPriorityFactors[];
+    /**
+     * 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 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
+     */
+    allocateResources(priorities: GoalPriorityFactors[], strategy?: AllocationStrategy, momentumMap?: Map<string, MomentumInfo>, depSchedule?: DependencySchedule): CrossGoalAllocation[];
+    /**
+     * Recalculate priorities for all currently active goals and produce a new
+     * allocation plan.
+     *
+     * @param trigger — what caused this rebalance
+     * @param goalIds — explicit list of goal IDs to consider; if omitted, the
+     *                  IDs from the last calculateGoalPriorities call are used
+     */
+    rebalanceGoals(trigger: CrossGoalRebalanceTrigger, goalIds?: string[]): CrossGoalRebalanceResult;
+    /**
+     * Search the VectorIndex for strategy templates that match the given goal.
+     *
+     * Matching is based on:
+     *   1. Semantic similarity between the goal text and template hypothesis_pattern
+     *   2. domain_tags overlap (at least 1 tag in common with the goal's domain tags)
+     *   3. Final ranking: similarity × effectiveness_score (descending)
+     *
+     * The caller is responsible for having added StrategyTemplate objects to the
+     * VectorIndex with their `template_id` as the entry id and metadata shaped
+     * as StrategyTemplate fields.
+     *
+     * @param goalId — goal for which templates are requested
+     * @param vectorIndex — the index to search (typically the instance-level one,
+     *                      but callers may pass a different one for testing)
+     * @param limit — number of results to return (default 3)
+     */
+    getRecommendedTemplates(goalId: string, vectorIndex: VectorIndex, limit?: number): Promise<StrategyTemplate[]>;
+    /**
+     * Calculate momentum for a single goal based on recent state snapshots.
+     *
+     * @param goalId — goal to evaluate
+     * @param snapshots — array of recent progress values (0-1), ordered oldest → newest
+     *                    (typically last 5 iterations). Minimum 2 values required.
+     * @returns MomentumInfo
+     */
+    calculateMomentum(goalId: string, snapshots: number[]): MomentumInfo;
+    /**
+     * Build a phased dependency schedule for the given goals using the provided
+     * GoalDependencyGraph instance.
+     *
+     * The schedule uses topological sort to group goals into phases where all
+     * goals in a phase can run concurrently. Phase 0 contains goals with no
+     * prerequisites; subsequent phases contain goals whose prerequisites are
+     * all satisfied by earlier phases.
+     *
+     * The critical path is the longest chain of prerequisite edges through the
+     * DAG (measured in number of nodes).
+     *
+     * @param goalIds — IDs of goals to schedule
+     * @param graph — the GoalDependencyGraph instance to query
+     * @returns DependencySchedule
+     */
+    buildDependencySchedule(goalIds: string[], graph: GoalDependencyGraph): DependencySchedule;
+    /**
+     * 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)
+     */
+    rebalanceOnStall(currentAllocations: CrossGoalAllocation[], momentumMap: Map<string, MomentumInfo>): RebalanceAction[];
+    /**
+     * Compute the critical path (longest prerequisite chain) among the given goals.
+     * Returns the sequence of goalIds on the critical path.
+     */
+    private _computeCriticalPath;
+    /**
+     * Produce a rough [0,1] severity for a single goal dimension.
+     *
+     * For numeric thresholds we compute gap / scale.
+     * For binary thresholds (present/match) we return 0 or 1.
+     * Returns 0 when the dimension is already satisfied.
+     */
+    private _estimateDimensionGap;
+    /**
+     * Extract domain tags from a goal's constraints and title.
+     * Recognises constraints with format "domain:tagname" or "tag:tagname".
+     */
+    private _extractDomainTags;
+    /**
+     * Get a goal_id → resource_share map for the given goal IDs.
+     *
+     * Recomputes allocations based on current goal states.
+     * Returns a Map suitable for use by PortfolioManager.selectNextStrategyAcrossGoals().
+     */
+    getAllocationMap(goalIds: string[]): Map<string, number>;
+}
+//# sourceMappingURL=cross-goal-portfolio.d.ts.map

package/dist/cross-goal-portfolio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-goal-portfolio.d.ts","sourceRoot":"","sources":["../src/cross-goal-portfolio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D,OAAO,KAAK,EACV,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,yBAAyB,EACzB,YAAY,EAEZ,kBAAkB,EAElB,kBAAkB,EAClB,eAAe,EAChB,MAAM,4BAA4B,CAAC;AASpC;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,oEAAoE;IACpE,OAAO,CAAC,cAAc,CAA+C;gBAGnE,YAAY,EAAE,YAAY,EAC1B,mBAAmB,EAAE,mBAAmB,EACxC,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,gBAAgB,EACjC,MAAM,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC;IAW5C;;;;;;;;;;;;;;OAcG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,mBAAmB,EAAE;IA+KjE;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CACf,UAAU,EAAE,mBAAmB,EAAE,EACjC,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EACvC,WAAW,CAAC,EAAE,kBAAkB,GAC/B,mBAAmB,EAAE;IAuIxB;;;;;;;OAOG;IACH,cAAc,CACZ,OAAO,EAAE,yBAAyB,EAClC,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,wBAAwB;IAc3B;;;;;;;;;;;;;;;;OAgBG;IACG,uBAAuB,CAC3B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA6E9B;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,YAAY;IA6DpE;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CACrB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,mBAAmB,GACzB,kBAAkB;IA8ErB;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,kBAAkB,EAAE,mBAAmB,EAAE,EACzC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GACrC,eAAe,EAAE;IAgEpB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA+D5B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA4C7B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;;OAKG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAmBzD"}