conatus 0.1.0

package/dist/state-aggregator.js

@@ -0,0 +1,290 @@
+import { aggregateValues } from "./drive/satisficing-judge.js";
+import { computeRawGap, normalizeGap } from "./drive/gap-calculator.js";
+/**
+ * StateAggregator handles upward aggregation (children → parent) and
+ * downward propagation (parent → children) of goal state, plus cascade
+ * completion detection.
+ *
+ * Design ref: docs/design/goal-tree.md §5 (state aggregation) and §6 (state propagation).
+ */
+export class StateAggregator {
+    stateManager;
+    satisficingJudge;
+    /**
+     * In-memory registry of StateAggregationRules keyed by parent_id.
+     * Rules are injected via registerAggregationRule().
+     */
+    aggregationRules = new Map();
+    constructor(stateManager, satisficingJudge) {
+        this.stateManager = stateManager;
+        this.satisficingJudge = satisficingJudge;
+    }
+    /**
+     * Register (or replace) a StateAggregationRule for a parent goal.
+     * The rule overrides the default "min" aggregation for that parent.
+     */
+    registerAggregationRule(rule) {
+        this.aggregationRules.set(rule.parent_id, rule);
+    }
+    // ─── Upward Aggregation ───
+    /**
+     * Aggregate the current states of all direct children of parentId into a
+     * single AggregatedState.
+     *
+     * Algorithm (goal-tree.md §5):
+     *   1. Load parent goal to get children_ids.
+     *   2. For each child, compute a normalized gap (average of per-dimension gaps).
+     *   3. Determine aggregation method from registered rule or default "min".
+     *   4. Aggregate child gaps with the chosen method.
+     *   5. Confidence = min(child confidences) — conservative.
+     *
+     * @throws if the parent goal cannot be found.
+     */
+    aggregateChildStates(parentId) {
+        const parent = this.stateManager.loadGoal(parentId);
+        if (parent === null) {
+            throw new Error(`StateAggregator.aggregateChildStates: parent goal "${parentId}" not found`);
+        }
+        const childIds = parent.children_ids;
+        const childGaps = {};
+        const childCompletions = {};
+        const childConfidences = [];
+        for (const childId of childIds) {
+            const child = this.stateManager.loadGoal(childId);
+            if (child === null) {
+                // Missing child: treat as fully incomplete with low confidence
+                childGaps[childId] = 1.0;
+                childCompletions[childId] = false;
+                childConfidences.push(0);
+                continue;
+            }
+            const gap = computeChildGap(child);
+            childGaps[childId] = gap;
+            childCompletions[childId] = child.status === "completed";
+            const minConf = minChildConfidence(child);
+            childConfidences.push(minConf);
+        }
+        const aggregationMethod = this.resolveAggregationMethod(parentId);
+        let aggregatedGap;
+        if (childIds.length === 0) {
+            aggregatedGap = 0;
+        }
+        else {
+            const gapValues = childIds.map((id) => childGaps[id] ?? 1.0);
+            if (aggregationMethod === "all_required") {
+                // all_required: parent is blocked as long as any child is incomplete
+                // Express as minimum fulfillment ratio (1 - gap)
+                const fulfillmentRatios = gapValues.map((g) => 1 - g);
+                const minFulfillment = aggregateValues(fulfillmentRatios, "all_required");
+                aggregatedGap = 1 - minFulfillment;
+            }
+            else {
+                aggregatedGap = aggregateValues(gapValues, aggregationMethod);
+            }
+        }
+        const aggregatedConfidence = childConfidences.length > 0 ? Math.min(...childConfidences) : 1.0;
+        return {
+            parent_id: parentId,
+            aggregated_gap: Math.min(1, Math.max(0, aggregatedGap)),
+            aggregated_confidence: aggregatedConfidence,
+            child_gaps: childGaps,
+            child_completions: childCompletions,
+            aggregation_method: aggregationMethod,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    // ─── Downward Propagation ───
+    /**
+     * Propagate parent-level state changes down to all direct children.
+     *
+     * Two propagation types (goal-tree.md §5):
+     *   a. Constraint propagation: new parent constraints are appended to children
+     *      that don't already have them (idempotent).
+     *   b. Deadline propagation: if the parent deadline differs from the children's
+     *      proportional position, adjust each child's deadline proportionally.
+     *
+     * Note: this method reads the parent goal's CURRENT deadline; to propagate a
+     * deadline change the caller must first save the updated parent, then call
+     * propagateStateDown().
+     *
+     * @throws if the parent goal cannot be found.
+     */
+    propagateStateDown(parentId) {
+        const parent = this.stateManager.loadGoal(parentId);
+        if (parent === null) {
+            throw new Error(`StateAggregator.propagateStateDown: parent goal "${parentId}" not found`);
+        }
+        const parentDeadlineMs = parseDeadlineMs(parent.deadline);
+        const now = Date.now();
+        for (const childId of parent.children_ids) {
+            const child = this.stateManager.loadGoal(childId);
+            if (child === null)
+                continue;
+            let updated = { ...child };
+            // ─── a. Constraint propagation ───
+            const existingConstraints = new Set(child.constraints);
+            const newConstraints = parent.constraints.filter((c) => !existingConstraints.has(c));
+            if (newConstraints.length > 0) {
+                updated = {
+                    ...updated,
+                    constraints: [...child.constraints, ...newConstraints],
+                };
+            }
+            // ─── b. Deadline propagation ───
+            if (parentDeadlineMs !== null) {
+                const childDeadlineMs = parseDeadlineMs(child.deadline);
+                if (childDeadlineMs !== null) {
+                    // Proportional adjustment:
+                    //   remaining_parent = parentDeadline - now
+                    //   remaining_child  = childDeadline - now
+                    //   ratio = remaining_parent / original_remaining_parent
+                    // Since we don't store the "original" parent deadline, we derive
+                    // the ratio from how much of the parent's window is left relative
+                    // to the child's remaining window.  The simplest safe approach
+                    // (matching goal-tree.md §5) is:
+                    //   new_child_deadline = now + (childRemainingMs / parentRemainingMs) * parentRemainingMs
+                    // which simplifies to: keep child proportional within parent's window.
+                    //
+                    // Concretely: child gets the same ratio of parent's deadline window
+                    // as the child's remaining time relative to the parent.
+                    const parentRemainingMs = parentDeadlineMs - now;
+                    const childRemainingMs = childDeadlineMs - now;
+                    if (parentRemainingMs > 0 && childRemainingMs !== parentRemainingMs) {
+                        // New child deadline = now + min(childRemainingMs, parentRemainingMs)
+                        // so the child is never later than the parent.
+                        const newChildRemainingMs = Math.min(childRemainingMs, parentRemainingMs);
+                        const newChildDeadlineMs = now + newChildRemainingMs;
+                        updated = {
+                            ...updated,
+                            deadline: new Date(newChildDeadlineMs).toISOString(),
+                        };
+                    }
+                }
+            }
+            if (updated.constraints !== child.constraints ||
+                updated.deadline !== child.deadline) {
+                this.stateManager.saveGoal({
+                    ...updated,
+                    updated_at: new Date().toISOString(),
+                });
+            }
+        }
+    }
+    // ─── Completion Cascade ───
+    /**
+     * Walk up the tree from goalId and return IDs of ancestors that have
+     * become eligible for completion because ALL of their children are either
+     * "completed" or cancelled (treated as pruned-and-done).
+     *
+     * The starting goalId is treated as if it were already completed — this
+     * allows callers to invoke checkCompletionCascade immediately after deciding
+     * to complete a goal, before the status has been persisted.
+     *
+     * This method does NOT mutate any goal status — the caller decides what to
+     * do with the returned list (e.g. mark them "completed").
+     *
+     * @param goalId Starting point (usually the goal that just completed).
+     * @returns Ordered array of newly-completable ancestor IDs (bottom-up order).
+     */
+    checkCompletionCascade(goalId) {
+        const completable = [];
+        // Track which goals are effectively complete for the purpose of this walk.
+        // The starting goal is treated as complete even if its DB status is "active".
+        const effectivelyComplete = new Set([goalId]);
+        let currentId = goalId;
+        // Walk up the parent chain
+        while (currentId !== null) {
+            const current = this.stateManager.loadGoal(currentId);
+            if (current === null)
+                break;
+            const parentId = current.parent_id;
+            if (parentId === null)
+                break; // reached root — stop (root itself has no parent to cascade to)
+            const parent = this.stateManager.loadGoal(parentId);
+            if (parent === null)
+                break;
+            // Check whether ALL children of the parent are done
+            const allChildrenDone = parent.children_ids.every((childId) => {
+                if (effectivelyComplete.has(childId))
+                    return true; // treated as complete
+                const child = this.stateManager.loadGoal(childId);
+                if (child === null)
+                    return false; // unknown child → not done
+                if (child.status === "completed")
+                    return true;
+                // cancelled counts as done (covers "merged" / pruned nodes)
+                if (child.status === "cancelled")
+                    return true;
+                return false;
+            });
+            if (!allChildrenDone)
+                break; // stop cascade — parent still blocked
+            completable.push(parentId);
+            // Mark parent as effectively complete so its own parent sees it as done
+            effectivelyComplete.add(parentId);
+            currentId = parentId;
+        }
+        return completable;
+    }
+    // ─── Helpers ───
+    resolveAggregationMethod(parentId) {
+        const rule = this.aggregationRules.get(parentId);
+        return rule?.aggregation ?? "min";
+    }
+}
+// ─── Module-level pure helpers ───
+/**
+ * Compute a normalized gap in [0, 1] for a goal by averaging the normalized
+ * gap of each of its dimensions.
+ *
+ * Per-dimension formula (simplified, matches task spec):
+ *   min threshold: max(0, (target - current) / target)  [guard: target=0 → 0 or 1]
+ *   max threshold: max(0, (current - target) / target)  [guard: target=0 → 0 or 1]
+ *   default:       |current - target| / max(|target|, 1)
+ *
+ * When current_value is null, the dimension gap is 1 (fully unmet).
+ * When there are no dimensions, gap = 0 (consider it done).
+ */
+function computeChildGap(goal) {
+    if (goal.dimensions.length === 0)
+        return 0;
+    // If the goal is already completed/cancelled, gap = 0
+    if (goal.status === "completed" || goal.status === "cancelled")
+        return 0;
+    const dimGaps = goal.dimensions.map((dim) => computeDimensionGapSimple(dim));
+    const sum = dimGaps.reduce((acc, g) => acc + g, 0);
+    return Math.min(1, Math.max(0, sum / dimGaps.length));
+}
+/**
+ * Compute a simple normalized gap [0,1] for a single dimension.
+ * Uses the formulas from the task spec rather than the full
+ * confidence-weighted pipeline (which is used by GapCalculator for drive scoring).
+ */
+function computeDimensionGapSimple(dim) {
+    const { current_value, threshold } = dim;
+    if (current_value === null)
+        return 1;
+    const rawGap = computeRawGap(current_value, threshold);
+    const normalizedGap = normalizeGap(rawGap, threshold, current_value);
+    return Math.min(1, Math.max(0, normalizedGap));
+}
+/**
+ * Compute the minimum confidence across all dimensions of a goal.
+ * Returns 1.0 when there are no dimensions (nothing uncertain).
+ */
+function minChildConfidence(goal) {
+    if (goal.dimensions.length === 0)
+        return 1.0;
+    return Math.min(...goal.dimensions.map((d) => d.confidence));
+}
+/**
+ * Parse an ISO 8601 deadline string into milliseconds since epoch.
+ * Returns null if the deadline is null or unparseable.
+ */
+function parseDeadlineMs(deadline) {
+    if (deadline === null)
+        return null;
+    const ms = Date.parse(deadline);
+    return isNaN(ms) ? null : ms;
+}
+//# sourceMappingURL=state-aggregator.js.map

package/dist/state-aggregator.js.map

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

package/dist/state-manager.d.ts

@@ -0,0 +1,121 @@
+import type { Logger } from "./runtime/logger.js";
+import type { Goal, GoalTree } from "./types/goal.js";
+import type { ObservationLog, ObservationLogEntry } from "./types/state.js";
+import type { RescheduleOptions } from "./types/state.js";
+import type { GapHistoryEntry } from "./types/gap.js";
+import type { PaceSnapshot } from "./types/goal.js";
+/**
+ * StateManager handles persistence of goals, state vectors, observation logs,
+ * and gap history under a base directory (default: ~/.motiva/).
+ *
+ * File layout:
+ *   <base>/goals/<goal_id>/goal.json
+ *   <base>/goals/<goal_id>/observations.json
+ *   <base>/goals/<goal_id>/gap-history.json
+ *   <base>/goal-trees/<root_id>.json
+ *   <base>/events/              (event queue directory)
+ *   <base>/events/archive/      (processed events)
+ *   <base>/reports/             (report output directory)
+ *
+ * All writes are atomic: write to .tmp file, then rename.
+ */
+export declare class StateManager {
+    private readonly baseDir;
+    private readonly logger?;
+    constructor(baseDir?: string, logger?: Logger);
+    /** Create required subdirectories. Must be called after construction before first use. */
+    init(): Promise<void>;
+    /** Returns the base directory path */
+    getBaseDir(): string;
+    private goalDir;
+    private atomicWrite;
+    private atomicRead;
+    saveGoal(goal: Goal): Promise<void>;
+    loadGoal(goalId: string): Promise<Goal | null>;
+    deleteGoal(goalId: string): Promise<boolean>;
+    /**
+     * Archive a completed goal by moving its state files to
+     * <base>/archive/<goalId>/.
+     *
+     * Moves:
+     *   goals/<goalId>/         → archive/<goalId>/goal/
+     *   tasks/<goalId>/         → archive/<goalId>/tasks/    (if exists)
+     *   strategies/<goalId>/    → archive/<goalId>/strategies/ (if exists)
+     *   stalls/<goalId>.json    → archive/<goalId>/stalls.json (if exists)
+     *   reports/<goalId>/       → archive/<goalId>/reports/  (if exists)
+     *
+     * Returns true if the goal was archived, false if the goal was not found.
+     */
+    archiveGoal(goalId: string): Promise<boolean>;
+    /**
+     * Returns the goal IDs of all archived goals under <base>/archive/.
+     */
+    listArchivedGoals(): Promise<string[]>;
+    listGoalIds(): Promise<string[]>;
+    saveGoalTree(tree: GoalTree): Promise<void>;
+    loadGoalTree(rootId: string): Promise<GoalTree | null>;
+    deleteGoalTree(rootId: string): Promise<boolean>;
+    saveObservationLog(log: ObservationLog): Promise<void>;
+    loadObservationLog(goalId: string): Promise<ObservationLog | null>;
+    appendObservation(goalId: string, entry: ObservationLogEntry): Promise<void>;
+    saveGapHistory(goalId: string, history: GapHistoryEntry[]): Promise<void>;
+    loadGapHistory(goalId: string): Promise<GapHistoryEntry[]>;
+    appendGapHistoryEntry(goalId: string, entry: GapHistoryEntry): Promise<void>;
+    /**
+     * Returns all goals with node_type === "milestone".
+     */
+    getMilestones(goals: Goal[]): Goal[];
+    /**
+     * Returns milestones whose target_date is in the past (overdue).
+     * Goals without a target_date are excluded.
+     */
+    getOverdueMilestones(goals: Goal[]): Goal[];
+    /**
+     * Evaluate pace for a milestone goal.
+     * currentAchievement (0-1) is computed by the caller (e.g. from SatisficingJudge).
+     *
+     * Pace evaluation logic (state-vector.md §8):
+     *   elapsed_ratio = time_elapsed / total_duration   (creation → target_date)
+     *   achievement_ratio = currentAchievement          (0-1)
+     *   pace_ratio = achievement_ratio / elapsed_ratio  (guard divide-by-zero)
+     *   on_track: pace_ratio >= 0.8
+     *   at_risk:  pace_ratio >= 0.5
+     *   behind:   pace_ratio < 0.5
+     *
+     * If no target_date is set, returns on_track with pace_ratio = 1.
+     */
+    evaluatePace(milestone: Goal, currentAchievement: number): PaceSnapshot;
+    /**
+     * Save a pace snapshot to a milestone goal (persists to disk).
+     */
+    savePaceSnapshot(goalId: string, snapshot: PaceSnapshot): Promise<void>;
+    /**
+     * Generate reschedule options when a milestone is behind.
+     * Always returns 3 options: extend_deadline, reduce_target, renegotiate.
+     */
+    generateRescheduleOptions(milestone: Goal, currentAchievement: number): RescheduleOptions;
+    /**
+     * Get the full goal tree rooted at rootId.
+     * Returns null if the root goal doesn't exist.
+     * Returns goals in BFS order: root first, then children level by level.
+     */
+    getGoalTree(rootId: string): Promise<Goal[] | null>;
+    /**
+     * Get all goals in the subtree of goalId (including goalId itself).
+     * Returns [] if goal not found.
+     */
+    getSubtree(goalId: string): Promise<Goal[]>;
+    /**
+     * Update a goal that belongs to a tree, handling both goal and tree consistency.
+     * Merges updates into the existing goal, preserving its id.
+     * If the goal has a parent_id, ensures the parent's children_ids still includes this goal.
+     */
+    updateGoalInTree(goalId: string, updates: Partial<Goal>): Promise<void>;
+    /** Check whether a goal directory exists */
+    goalExists(goalId: string): Promise<boolean>;
+    /** Read raw JSON from any path relative to base dir */
+    readRaw(relativePath: string): Promise<unknown | null>;
+    /** Write raw JSON to any path relative to base dir (atomic) */
+    writeRaw(relativePath: string, data: unknown): Promise<void>;
+}
+//# sourceMappingURL=state-manager.d.ts.map

package/dist/state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../src/state-manager.ts"],"names":[],"mappings":"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"}