pulseed 0.0.1 → 0.1.1

package/dist/drive/gap-calculator.js

@@ -0,0 +1,234 @@
+/**
+ * GapCalculator implements the gap calculation pipeline defined in gap-calculation.md:
+ *   raw_gap -> normalized_gap -> normalized_weighted_gap
+ *
+ * All functions are pure (no side effects).
+ *
+ * Key design constraints:
+ * - Confidence adjustment applies ONLY at the normalized_weighted_gap stage (section 3).
+ * - null current_value => maximum gap, no confidence weighting applied.
+ * - Zero-division guards: if denominator is 0, normalized_gap = 1.0 (if raw_gap > 0) or 0.0.
+ */
+// ─── Step 1: Raw Gap Calculation ───
+/**
+ * Compute raw gap for a single dimension based on its threshold type.
+ *
+ * Formulas from gap-calculation.md section 1:
+ *   min(N):        max(0, threshold - current)
+ *   max(N):        max(0, current - threshold)
+ *   range(lo, hi): max(0, lo - current) + max(0, current - hi)
+ *   present:       0 if truthy, 1 if falsy
+ *   match(value):  0 if current == value, 1 otherwise
+ *
+ * Guard: current_value = null => maximum gap
+ *   numeric types: threshold value (representing full undershoot)
+ *   binary types:  1
+ */
+export function computeRawGap(currentValue, threshold) {
+    // Guard: null current_value
+    if (currentValue === null) {
+        switch (threshold.type) {
+            case "min":
+                return threshold.value; // full gap = threshold itself
+            case "max":
+                // null current_value on a max threshold: unknown exceedance.
+                // Formula for max is `current - threshold`; with null current we
+                // return a positive sentinel so normalizeGap's null guard (→ 1.0)
+                // takes over. Use max(threshold.value, 1) to stay positive when
+                // threshold.value = 0.
+                return threshold.value > 0 ? threshold.value : 1;
+            case "range":
+                return threshold.high - threshold.low; // full range span
+            case "present":
+                return 1;
+            case "match":
+                return 1;
+        }
+    }
+    switch (threshold.type) {
+        case "min": {
+            const current = toNumber(currentValue);
+            return Math.max(0, threshold.value - current);
+        }
+        case "max": {
+            const current = toNumber(currentValue);
+            return Math.max(0, current - threshold.value);
+        }
+        case "range": {
+            const current = toNumber(currentValue);
+            return (Math.max(0, threshold.low - current) +
+                Math.max(0, current - threshold.high));
+        }
+        case "present": {
+            return isTruthy(currentValue) ? 0 : 1;
+        }
+        case "match": {
+            // Strict equality comparison for match type
+            return currentValue === threshold.value ? 0 : 1;
+        }
+    }
+}
+// ─── Step 2: Normalization ───
+/**
+ * Normalize raw gap to [0, 1] range.
+ *
+ * Formulas from gap-calculation.md section 2:
+ *   min(N):        raw_gap / threshold (guard: if threshold=0 and raw_gap>0 -> 1.0)
+ *   max(N):        raw_gap / threshold (guard: if threshold=0 -> cap at 1.0)
+ *   range(lo, hi): min(1.0, raw_gap / ((high - low) / 2))
+ *   present:       raw_gap (already 0 or 1)
+ *   match:         raw_gap (already 0 or 1)
+ *
+ * null current_value => normalized_gap = 1.0
+ */
+export function normalizeGap(rawGap, threshold, currentValue) {
+    // Guard: null current_value => maximum gap
+    if (currentValue === null) {
+        return 1.0;
+    }
+    switch (threshold.type) {
+        case "min": {
+            if (threshold.value === 0) {
+                return rawGap > 0 ? 1.0 : 0.0;
+            }
+            return rawGap / threshold.value;
+        }
+        case "max": {
+            if (threshold.value === 0) {
+                return Math.min(rawGap, 1.0);
+            }
+            return rawGap / threshold.value;
+        }
+        case "range": {
+            const halfWidth = (threshold.high - threshold.low) / 2;
+            if (halfWidth === 0) {
+                return rawGap > 0 ? 1.0 : 0.0;
+            }
+            return Math.min(1.0, rawGap / halfWidth);
+        }
+        case "present":
+        case "match":
+            return rawGap; // already 0 or 1
+    }
+}
+// ─── Step 3: Confidence-Weighted Gap ───
+/**
+ * Apply confidence weighting to the normalized gap.
+ *
+ * Formula from gap-calculation.md section 3:
+ *   normalized_weighted_gap = normalized_gap * (1 + (1 - confidence) * uncertainty_weight)
+ *
+ * Key constraint: if current_value is null, skip confidence weighting
+ * (null already produces max gap via section 1 guard; don't double-inflate).
+ */
+export function applyConfidenceWeight(normalizedGap, confidence, uncertaintyWeight, currentValueIsNull) {
+    if (currentValueIsNull) {
+        return normalizedGap; // Do not apply confidence weighting for null values
+    }
+    const weighted = normalizedGap * (1 + (1 - confidence) * uncertaintyWeight);
+    return Math.min(1.0, weighted);
+}
+/**
+ * Calculate the complete gap pipeline for a single dimension.
+ * Returns all intermediate values for transparency.
+ */
+export function calculateDimensionGap(input, globalUncertaintyWeight = 1.0) {
+    const { name, current_value, threshold, confidence, uncertainty_weight } = input;
+    const effectiveWeight = uncertainty_weight ?? globalUncertaintyWeight;
+    const rawGap = computeRawGap(current_value, threshold);
+    const normalizedGap = normalizeGap(rawGap, threshold, current_value);
+    const normalizedWeightedGap = applyConfidenceWeight(normalizedGap, confidence, effectiveWeight, current_value === null);
+    return {
+        dimension_name: name,
+        raw_gap: rawGap,
+        normalized_gap: normalizedGap,
+        normalized_weighted_gap: normalizedWeightedGap,
+        confidence,
+        uncertainty_weight: effectiveWeight,
+    };
+}
+// ─── Full Pipeline for a Goal ───
+/**
+ * Calculate gap vector for all dimensions of a goal.
+ */
+export function calculateGapVector(goalId, dimensions, globalUncertaintyWeight = 1.0) {
+    const gaps = dimensions.map((dim) => calculateDimensionGap({
+        name: dim.name,
+        current_value: dim.current_value,
+        threshold: dim.threshold,
+        confidence: dim.confidence,
+        uncertainty_weight: dim.uncertainty_weight,
+    }, globalUncertaintyWeight));
+    return {
+        goal_id: goalId,
+        gaps,
+        timestamp: new Date().toISOString(),
+    };
+}
+// ─── Parent Gap Aggregation ───
+/**
+ * Aggregate child gap vectors into a parent gap value.
+ *
+ * gap-calculation.md section 6:
+ *   Default: bottleneck aggregation = max(normalized_weighted_gap)
+ *   Alternative: weighted_avg, sum
+ *
+ * Operates on normalized_weighted_gap values.
+ */
+export function aggregateGaps(childGaps, method = "max", weights) {
+    if (childGaps.length === 0)
+        return 0;
+    switch (method) {
+        case "max":
+            return Math.max(...childGaps);
+        case "weighted_avg": {
+            const w = weights ?? childGaps.map(() => 1);
+            const totalWeight = w.reduce((sum, wi) => sum + wi, 0);
+            if (totalWeight === 0)
+                return 0;
+            const weightedSum = childGaps.reduce((sum, gap, i) => sum + gap * (w[i] ?? 1), 0);
+            return weightedSum / totalWeight;
+        }
+        case "sum":
+            return childGaps.reduce((sum, gap) => sum + gap, 0);
+    }
+}
+// ─── Convenience Helper ───
+/**
+ * Compute normalized progress [0,1] for a dimension.
+ * Returns null if value or threshold is missing.
+ *
+ * Progress = 1 - clamp(normalizedGap, 0, 1), where normalizedGap is derived
+ * from the raw gap pipeline (computeRawGap → normalizeGap).
+ */
+export function dimensionProgress(currentValue, threshold) {
+    if (currentValue === null || currentValue === undefined || !threshold)
+        return null;
+    const rawGap = computeRawGap(currentValue, threshold);
+    const normalizedGap = normalizeGap(rawGap, threshold, currentValue);
+    return 1 - Math.max(0, Math.min(1, normalizedGap));
+}
+// ─── Helpers ───
+function toNumber(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "string") {
+        const n = Number(value);
+        return isNaN(n) ? 0 : n;
+    }
+    return 0;
+}
+function isTruthy(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return value !== 0;
+    if (typeof value === "string")
+        return value.length > 0;
+    return false;
+}
+//# sourceMappingURL=gap-calculator.js.map

package/dist/drive/gap-calculator.js.map

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

package/dist/drive/reward-log.d.ts

@@ -0,0 +1,51 @@
+/**
+ * reward-log.ts
+ *
+ * Consolidated JSON log output for the reward (drive score) computation.
+ * Controlled by the PULSEED_REWARD_LOG environment variable.
+ *
+ * Usage:
+ *   PULSEED_REWARD_LOG=1 pulseed run <goal>
+ *
+ * Each log line is a single JSON object written to stderr so it does not
+ * pollute stdout / TUI output. Default: OFF.
+ */
+import type { DriveScore } from "../types/drive.js";
+import type { CompletionJudgment } from "../types/satisficing.js";
+export interface RewardLogEntry {
+    ts: string;
+    goal_id: string;
+    iteration: number;
+    gap_aggregate: number;
+    confidence_avg: number;
+    trust_score: number | null;
+    drive_scores: Array<{
+        dimension: string;
+        dissatisfaction: number;
+        deadline: number;
+        opportunity: number;
+        final_score: number;
+        dominant_drive: string;
+    }>;
+    top_dimension: string | null;
+    is_complete: boolean;
+    blocking_dimensions: string[];
+}
+/**
+ * Returns true when PULSEED_REWARD_LOG=1 is set in the environment.
+ */
+export declare function isRewardLogEnabled(): boolean;
+/**
+ * Emit a single JSON line to stderr with all major reward computation inputs/outputs.
+ * No-op when PULSEED_REWARD_LOG is not set to "1".
+ */
+export declare function logRewardComputation(params: {
+    goalId: string;
+    iteration: number;
+    gapAggregate: number;
+    confidenceAvg: number;
+    trustScore: number | null;
+    driveScores: DriveScore[];
+    completionJudgment: CompletionJudgment | null;
+}): void;
+//# sourceMappingURL=reward-log.d.ts.map

package/dist/drive/reward-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reward-log.d.ts","sourceRoot":"","sources":["../../src/drive/reward-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,KAAK,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC/C,GAAG,IAAI,CAyBP"}

package/dist/drive/reward-log.js

@@ -0,0 +1,48 @@
+/**
+ * reward-log.ts
+ *
+ * Consolidated JSON log output for the reward (drive score) computation.
+ * Controlled by the PULSEED_REWARD_LOG environment variable.
+ *
+ * Usage:
+ *   PULSEED_REWARD_LOG=1 pulseed run <goal>
+ *
+ * Each log line is a single JSON object written to stderr so it does not
+ * pollute stdout / TUI output. Default: OFF.
+ */
+/**
+ * Returns true when PULSEED_REWARD_LOG=1 is set in the environment.
+ */
+export function isRewardLogEnabled() {
+    return process.env["PULSEED_REWARD_LOG"] === "1";
+}
+/**
+ * Emit a single JSON line to stderr with all major reward computation inputs/outputs.
+ * No-op when PULSEED_REWARD_LOG is not set to "1".
+ */
+export function logRewardComputation(params) {
+    if (!isRewardLogEnabled())
+        return;
+    const entry = {
+        ts: new Date().toISOString(),
+        goal_id: params.goalId,
+        iteration: params.iteration,
+        gap_aggregate: params.gapAggregate,
+        confidence_avg: params.confidenceAvg,
+        trust_score: params.trustScore,
+        drive_scores: params.driveScores.map((s) => ({
+            dimension: s.dimension_name,
+            dissatisfaction: s.dissatisfaction,
+            deadline: s.deadline,
+            opportunity: s.opportunity,
+            final_score: s.final_score,
+            dominant_drive: s.dominant_drive,
+        })),
+        // assumes driveScores sorted by score desc (caller contract)
+        top_dimension: params.driveScores[0]?.dimension_name ?? null,
+        is_complete: params.completionJudgment?.is_complete ?? false,
+        blocking_dimensions: params.completionJudgment?.blocking_dimensions ?? [],
+    };
+    process.stderr.write(JSON.stringify(entry) + "\n");
+}
+//# sourceMappingURL=reward-log.js.map

package/dist/drive/reward-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reward-log.js","sourceRoot":"","sources":["../../src/drive/reward-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyBH;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,KAAK,GAAG,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAQpC;IACC,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO;IAElC,MAAM,KAAK,GAAmB;QAC5B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,OAAO,EAAE,MAAM,CAAC,MAAM;QACtB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,aAAa,EAAE,MAAM,CAAC,YAAY;QAClC,cAAc,EAAE,MAAM,CAAC,aAAa;QACpC,WAAW,EAAE,MAAM,CAAC,UAAU;QAC9B,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3C,SAAS,EAAE,CAAC,CAAC,cAAc;YAC3B,eAAe,EAAE,CAAC,CAAC,eAAe;YAClC,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,cAAc,EAAE,CAAC,CAAC,cAAc;SACjC,CAAC,CAAC;QACH,6DAA6D;QAC7D,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,cAAc,IAAI,IAAI;QAC5D,WAAW,EAAE,MAAM,CAAC,kBAAkB,EAAE,WAAW,IAAI,KAAK;QAC5D,mBAAmB,EAAE,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,IAAI,EAAE;KAC1E,CAAC;IAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC"}

package/dist/drive/satisficing-helpers.d.ts

@@ -0,0 +1,28 @@
+import type { Dimension } from "../types/goal.js";
+/**
+ * Aggregate an array of numeric values using the specified strategy.
+ *
+ * @param values - Numeric values to aggregate.
+ * @param aggregation - Strategy: "min" | "avg" | "max" | "all_required".
+ * @param thresholds - For "all_required": fulfillment ratios are already computed (values = ratios).
+ * @returns Aggregated value, or 0 if values array is empty.
+ */
+export declare function aggregateValues(values: number[], aggregation: "min" | "avg" | "max" | "all_required", thresholds?: number[]): number;
+export declare function toNumber(value: number | string | boolean | null): number;
+export declare function isTruthy(value: number | string | boolean | null): boolean;
+export declare function toNumberOrNull(value: number | string | boolean | null): number | null;
+/**
+ * Extract a representative numeric threshold value for the DimensionSatisfaction schema.
+ * Returns null for "present" (no numeric threshold).
+ */
+export declare function getNumericThresholdValue(dim: Dimension): number | null;
+/**
+ * Returns the numeric threshold for adjustment proposals.
+ * Only applicable to numeric thresholds (min/max/range).
+ */
+export declare function getNumericThresholdValueForProposal(dim: Dimension): number | null;
+/**
+ * Compute the value that fully satisfies the threshold (for propagation).
+ */
+export declare function getSatisfiedValue(dim: Dimension): number | string | boolean | null;
+//# sourceMappingURL=satisficing-helpers.d.ts.map

package/dist/drive/satisficing-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"satisficing-helpers.d.ts","sourceRoot":"","sources":["../../src/drive/satisficing-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIlD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EAAE,EAChB,WAAW,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,cAAc,EACnD,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,MAAM,CAiBR;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,CAQxE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAMzE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAGrF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CActE;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAajF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAclF"}

package/dist/drive/satisficing-helpers.js

@@ -0,0 +1,111 @@
+// ─── Pure Helper: aggregateValues ───
+/**
+ * Aggregate an array of numeric values using the specified strategy.
+ *
+ * @param values - Numeric values to aggregate.
+ * @param aggregation - Strategy: "min" | "avg" | "max" | "all_required".
+ * @param thresholds - For "all_required": fulfillment ratios are already computed (values = ratios).
+ * @returns Aggregated value, or 0 if values array is empty.
+ */
+export function aggregateValues(values, aggregation, thresholds) {
+    if (values.length === 0)
+        return 0;
+    switch (aggregation) {
+        case "min":
+            return Math.min(...values);
+        case "max":
+            return Math.max(...values);
+        case "avg": {
+            const sum = values.reduce((acc, v) => acc + v, 0);
+            return sum / values.length;
+        }
+        case "all_required":
+            // values are fulfillment ratios (0..1); return the minimum ratio
+            // (parent is "complete" only if all ratios = 1.0, expressed as min)
+            return Math.min(...values);
+    }
+}
+// ─── Helpers ───
+export function toNumber(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "string") {
+        const n = Number(value);
+        return isNaN(n) ? 0 : n;
+    }
+    return 0;
+}
+export function isTruthy(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return value !== 0;
+    if (typeof value === "string")
+        return value.length > 0;
+    return false;
+}
+export function toNumberOrNull(value) {
+    if (value === null)
+        return null;
+    return toNumber(value);
+}
+/**
+ * Extract a representative numeric threshold value for the DimensionSatisfaction schema.
+ * Returns null for "present" (no numeric threshold).
+ */
+export function getNumericThresholdValue(dim) {
+    const { threshold } = dim;
+    switch (threshold.type) {
+        case "min":
+            return threshold.value;
+        case "max":
+            return threshold.value;
+        case "range":
+            return threshold.high; // use upper bound as representative
+        case "present":
+            return null;
+        case "match":
+            return typeof threshold.value === "number" ? threshold.value : null;
+    }
+}
+/**
+ * Returns the numeric threshold for adjustment proposals.
+ * Only applicable to numeric thresholds (min/max/range).
+ */
+export function getNumericThresholdValueForProposal(dim) {
+    const { threshold } = dim;
+    switch (threshold.type) {
+        case "min":
+            return threshold.value;
+        case "max":
+            return threshold.value;
+        case "range":
+            return threshold.high;
+        case "present":
+        case "match":
+            return null; // adjustment not meaningful for binary thresholds
+    }
+}
+/**
+ * Compute the value that fully satisfies the threshold (for propagation).
+ */
+export function getSatisfiedValue(dim) {
+    const { threshold } = dim;
+    switch (threshold.type) {
+        case "min":
+            return threshold.value;
+        case "max":
+            return threshold.value;
+        case "range":
+            return (threshold.low + threshold.high) / 2;
+        case "present":
+            return true;
+        case "match":
+            return threshold.value;
+    }
+}
+//# sourceMappingURL=satisficing-helpers.js.map

package/dist/drive/satisficing-helpers.js.map

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

package/dist/drive/satisficing-judge.d.ts

@@ -0,0 +1,140 @@
+import { StateManager } from "../state-manager.js";
+import type { Goal, Dimension } from "../types/goal.js";
+import type { CompletionJudgment, DimensionSatisfaction, IterationConstraints, ThresholdAdjustmentProposal, MappingProposal, ConvergenceJudgment, SatisficingStatus } from "../types/satisficing.js";
+import type { IEmbeddingClient } from "../knowledge/embedding-client.js";
+export { aggregateValues } from "./satisficing-helpers.js";
+/**
+ * SatisficingJudge implements the completion judgment logic defined in satisficing.md.
+ *
+ * Responsibility: determine whether a goal (or individual dimension) is "good enough"
+ * to declare done, applying progress ceilings based on confidence tiers.
+ *
+ * Key design rules:
+ * - Completion requires ALL dimensions satisfied AND no low-confidence dimensions.
+ * - Progress ceiling: high >= 0.85 → 1.0 | medium >= 0.50 → 0.85 | low < 0.50 → 0.60
+ * - These ceiling values are from satisficing.md (distinct from ObservationEngine ceilings).
+ * - null current_value is treated as fully unsatisfied.
+ */
+export declare class SatisficingJudge {
+    private readonly stateManager;
+    private readonly embeddingClient?;
+    private readonly onSatisficingJudgment?;
+    private readonly gapHistory;
+    private readonly satisficingStreak;
+    constructor(stateManager: StateManager, embeddingClient?: IEmbeddingClient, // Phase 2: for dimension mapping proposals
+    onSatisficingJudgment?: (goalId: string, satisfiedDimensions: string[]) => void);
+    /**
+     * Compute the variance of an array of numbers. Returns null if fewer than 2 values.
+     */
+    private computeVariance;
+    /**
+     * Record a gap observation for a goal dimension into the ring buffer.
+     * Pushes the gap value and trims to CONVERGENCE_WINDOW.
+     */
+    private recordGap;
+    /**
+     * Judge convergence for a single gap value against a threshold.
+     * Records the gap in the ring buffer, then evaluates:
+     *   - gap < threshold → satisficed (existing behavior)
+     *   - variance < ε AND gap ≤ threshold × 1.5 → converged_satisficed
+     *   - variance < ε AND gap > threshold × 1.5 → stalled
+     *   - otherwise → in_progress
+     *
+     * @param key      Unique key for the ring buffer (e.g., `${goalId}:${dimensionName}`)
+     * @param gap      Current normalized gap value [0, 1]
+     * @param threshold The satisficing threshold (normalized gap target, typically 0 means met)
+     */
+    judgeConvergence(key: string, gap: number, threshold: number): ConvergenceJudgment;
+    /**
+     * Clear the gap history ring buffer for a specific key.
+     * Call this when a goal is reset or completed.
+     */
+    clearGapHistory(key: string): void;
+    private getConfidenceTier;
+    private getCeiling;
+    /**
+     * Compute actual progress (0–1) toward satisfying a dimension.
+     * Progress = 1 - normalized_gap, clamped to [0, 1].
+     * For binary thresholds (present/match), either 0 or 1.
+     * null current_value = 0 progress.
+     */
+    private computeActualProgress;
+    /**
+     * Determine whether a dimension's current_value meets its threshold.
+     * Uses raw boolean logic (not gap magnitude) for the is_satisfied flag.
+     */
+    private isSatisfiedRaw;
+    /**
+     * Check if a single dimension is satisfied with appropriate confidence ceiling.
+     */
+    isDimensionSatisfied(dim: Dimension): DimensionSatisfaction;
+    /**
+     * Propose dimension mappings between subgoal and parent goal dimensions
+     * using embedding similarity.
+     */
+    proposeDimensionMapping(subgoalDimensions: Array<{
+        name: string;
+        description?: string;
+    }>, parentGoalDimensions: Array<{
+        name: string;
+        description?: string;
+    }>): Promise<MappingProposal[]>;
+    /**
+     * Determine if a goal is fully complete.
+     * Complete iff all dimensions are satisfied AND no dimension has low confidence.
+     *
+     * @param goal The goal to check.
+     * @param convergenceStatuses Optional map of dimension key → SatisficingStatus from judgeConvergence().
+     *   When a dimension's convergence status is "converged_satisficed", it is treated as satisfied
+     *   (gap has stabilized within acceptable range — good enough).
+     *   Keys should match the format used with judgeConvergence(): `${goalId}:${dimensionName}`.
+     */
+    isGoalComplete(goal: Goal, convergenceStatuses?: Map<string, SatisficingStatus>): CompletionJudgment;
+    /**
+     * Apply progress ceiling based on confidence tier.
+     * Returns min(actualProgress, ceiling).
+     */
+    applyProgressCeiling(actualProgress: number, confidence: number): number;
+    /**
+     * Select dimensions to focus on in the next iteration.
+     *
+     * Algorithm:
+     * 1. Exclude already-satisfied dimensions.
+     * 2. Among remaining, sort by drive score (highest first).
+     * 3. Take top max_dimensions.
+     */
+    selectDimensionsForIteration(dimensions: Dimension[], driveScores: Array<{
+        dimension_name: string;
+        score: number;
+    }>, constraints?: IterationConstraints): string[];
+    /**
+     * Detect dimensions where threshold adjustment may be warranted.
+     *
+     * Condition 1: >= 3 failures AND normalized_gap has not improved (no progress).
+     * Condition 2: all other dimensions satisfied, this one is still far from threshold.
+     */
+    detectThresholdAdjustmentNeeded(goal: Goal, failureCounts: Map<string, number>): Promise<ThresholdAdjustmentProposal[]>;
+    /**
+     * Judge completion of an entire goal tree by checking all children recursively.
+     * Non-leaf nodes are complete when all children are completed or cancelled(merged).
+     *
+     * @param rootId The ID of the root goal of the tree.
+     * @returns CompletionJudgment for the root node.
+     */
+    judgeTreeCompletion(rootId: string, convergenceStatuses?: Map<string, SatisficingStatus>): Promise<CompletionJudgment>;
+    /**
+     * Propagate subgoal completion to the parent goal's matching dimension.
+     *
+     * Phase 2: supports dimension_mapping for aggregation-based propagation.
+     * - If any subgoal dimension has dimension_mapping set, use aggregation path.
+     * - Mixed: mapped dimensions use aggregation; unmapped dimensions fall back to name matching.
+     * - Backwards compatible: if no dimensions have dimension_mapping, behaves like MVP.
+     *
+     * @param subgoalId The subgoal's ID (used for name matching in MVP path).
+     * @param parentGoalId The parent goal's ID to update.
+     * @param subgoalDimensions Optional subgoal dimensions for aggregation mapping.
+     *   When omitted, falls back to MVP name-based matching only.
+     */
+    propagateSubgoalCompletion(subgoalId: string, parentGoalId: string, subgoalDimensions?: import("../types/goal.js").Dimension[]): Promise<void>;
+}
+//# sourceMappingURL=satisficing-judge.d.ts.map

package/dist/drive/satisficing-judge.d.ts.map

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