conatus 0.1.0

package/dist/runtime/plugin-loader.d.ts

@@ -0,0 +1,78 @@
+import type { Logger } from "./logger.js";
+import { type PluginManifest, type PluginState, type PluginType } from "../types/plugin.js";
+import type { AdapterRegistry } from "../execution/adapter-layer.js";
+import type { DataSourceRegistry } from "../observation/data-source-adapter.js";
+import type { NotifierRegistry } from "./notifier-registry.js";
+/**
+ * Discovers, loads, validates, and registers plugins from ~/.conatus/plugins/.
+ *
+ * Design principles:
+ *  - Plugin load failures never crash Conatus. Every error is caught, logged,
+ *    and returned as an error-state PluginState.
+ *  - Supports both plugin.yaml and plugin.json manifest formats.
+ *  - Routes each plugin to the correct registry based on manifest.type.
+ */
+export declare class PluginLoader {
+    private adapterRegistry;
+    private dataSourceRegistry;
+    private notifierRegistry;
+    private pluginsDir;
+    private pluginStates;
+    private readonly logger?;
+    constructor(adapterRegistry: AdapterRegistry, dataSourceRegistry: DataSourceRegistry, notifierRegistry: NotifierRegistry, pluginsDir?: string, logger?: Logger);
+    /**
+     * Discover all plugin directories and attempt to load each one.
+     * Returns a PluginState for every candidate directory (success or error).
+     */
+    loadAll(): Promise<PluginState[]>;
+    /**
+     * Load a single plugin from the given directory.
+     * Throws on any failure (caller catches and converts to error state).
+     */
+    loadOne(pluginDir: string): Promise<PluginState>;
+    /**
+     * Scan pluginsDir for subdirectories that contain plugin.yaml or plugin.json.
+     */
+    discoverPluginDirs(): Promise<string[]>;
+    /**
+     * Read and parse the plugin manifest (plugin.yaml or plugin.json).
+     * Validates against PluginManifestSchema.
+     */
+    loadManifest(pluginDir: string): Promise<PluginManifest>;
+    /**
+     * Check that the plugin implementation exports all required methods for its type.
+     */
+    validateInterface(type: PluginType, impl: unknown): void;
+    /**
+     * Register the plugin implementation in the appropriate registry.
+     */
+    registerPlugin(manifest: PluginManifest, impl: unknown, _pluginDir: string): Promise<void>;
+    buildSuccessState(manifest: PluginManifest): PluginState;
+    buildIncompatibleState(manifest: PluginManifest, motivaVersion: string, range: string): PluginState;
+    buildErrorState(pluginDir: string, reason: unknown): PluginState;
+    /**
+     * Return the PluginState for a given plugin name, or null if not found.
+     */
+    getPluginState(pluginName: string): PluginState | null;
+    /**
+     * Update the in-memory plugin state and persist to disk.
+     */
+    updatePluginState(pluginName: string, updates: Partial<Pick<PluginState, "trust_score" | "usage_count" | "success_count" | "failure_count">>): Promise<void>;
+    private hasManifestFile;
+}
+export declare function parseSemver(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export declare function compareSemver(a: {
+    major: number;
+    minor: number;
+    patch: number;
+}, b: {
+    major: number;
+    minor: number;
+    patch: number;
+}): -1 | 0 | 1;
+export declare function satisfiesRange(version: string, min?: string, max?: string): boolean;
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/runtime/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../src/runtime/plugin-loader.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,eAAe,EAAY,MAAM,+BAA+B,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,uCAAuC,CAAC;AACpG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI/D;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAG/B,eAAe,EAAE,eAAe,EAChC,kBAAkB,EAAE,kBAAkB,EACtC,gBAAgB,EAAE,gBAAgB,EAClC,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM;IASjB;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAiBvC;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAkDtD;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA4B7C;;;OAGG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA4C9D;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAiBxD;;OAEG;IACG,cAAc,CAClB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAgBhB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,WAAW;IAexD,sBAAsB,CAAC,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW;IAgBnG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,WAAW;IA6BhE;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAItD;;OAEG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,CAAC,CAAC,GACrG,OAAO,CAAC,IAAI,CAAC;YAeF,eAAe;CAW9B;AAyBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAI5F;AAED,wBAAgB,aAAa,CAC3B,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAClD,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAKZ;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAKnF"}

package/dist/runtime/plugin-loader.js

@@ -0,0 +1,349 @@
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+import * as url from "node:url";
+import yaml from "js-yaml";
+import { getPluginsDir } from "../utils/paths.js";
+import { writeJsonFileAtomic } from "../utils/json-io.js";
+import { ValidationError } from "../utils/errors.js";
+import { PluginManifestSchema, PluginStateSchema, } from "../types/plugin.js";
+// ─── PluginLoader ───
+/**
+ * Discovers, loads, validates, and registers plugins from ~/.conatus/plugins/.
+ *
+ * Design principles:
+ *  - Plugin load failures never crash Conatus. Every error is caught, logged,
+ *    and returned as an error-state PluginState.
+ *  - Supports both plugin.yaml and plugin.json manifest formats.
+ *  - Routes each plugin to the correct registry based on manifest.type.
+ */
+export class PluginLoader {
+    adapterRegistry;
+    dataSourceRegistry;
+    notifierRegistry;
+    pluginsDir;
+    pluginStates = new Map();
+    logger;
+    constructor(adapterRegistry, dataSourceRegistry, notifierRegistry, pluginsDir, logger) {
+        this.adapterRegistry = adapterRegistry;
+        this.dataSourceRegistry = dataSourceRegistry;
+        this.notifierRegistry = notifierRegistry;
+        this.pluginsDir = pluginsDir ?? getPluginsDir();
+        this.logger = logger;
+    }
+    /**
+     * Discover all plugin directories and attempt to load each one.
+     * Returns a PluginState for every candidate directory (success or error).
+     */
+    async loadAll() {
+        const pluginDirs = await this.discoverPluginDirs();
+        if (pluginDirs.length === 0) {
+            return [];
+        }
+        const results = await Promise.allSettled(pluginDirs.map((dir) => this.loadOne(dir)));
+        return results.map((r, i) => r.status === "fulfilled"
+            ? r.value
+            : this.buildErrorState(pluginDirs[i], r.reason));
+    }
+    /**
+     * Load a single plugin from the given directory.
+     * Throws on any failure (caller catches and converts to error state).
+     */
+    async loadOne(pluginDir) {
+        // 1. Read and validate manifest
+        const manifest = await this.loadManifest(pluginDir);
+        // 1b. Semver compatibility check
+        const motivaVersion = getMotivaVersion();
+        if (!satisfiesRange(motivaVersion, manifest.min_motiva_version, manifest.max_motiva_version)) {
+            const range = [
+                manifest.min_motiva_version ? `>=${manifest.min_motiva_version}` : "",
+                manifest.max_motiva_version ? `<=${manifest.max_motiva_version}` : "",
+            ]
+                .filter(Boolean)
+                .join(", ");
+            this.logger?.warn(`[PluginLoader] Skipping incompatible plugin "${manifest.name}": requires Conatus ${range}, got ${motivaVersion}`);
+            return this.buildIncompatibleState(manifest, motivaVersion, range);
+        }
+        // 2. Dynamically import the entry point
+        const entryPath = path.resolve(pluginDir, manifest.entry_point);
+        if (!entryPath.startsWith(pluginDir + path.sep) && entryPath !== pluginDir) {
+            throw new ValidationError(`Plugin entry point escapes plugin directory: ${manifest.entry_point}`);
+        }
+        let module;
+        try {
+            // Use pathToFileURL for cross-platform compatibility in ESM
+            const { pathToFileURL } = await import("node:url");
+            module = (await import(pathToFileURL(entryPath).href));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to import plugin entry point: ${entryPath} — ${msg}`);
+        }
+        const impl = module.default;
+        if (impl === undefined || impl === null) {
+            throw new Error(`Plugin entry point has no default export: ${entryPath}`);
+        }
+        // 3. Validate interface compliance
+        this.validateInterface(manifest.type, impl);
+        // 4. Register in the appropriate registry
+        await this.registerPlugin(manifest, impl, pluginDir);
+        return this.buildSuccessState(manifest);
+    }
+    /**
+     * Scan pluginsDir for subdirectories that contain plugin.yaml or plugin.json.
+     */
+    async discoverPluginDirs() {
+        let entries;
+        try {
+            entries = await fs.readdir(this.pluginsDir);
+        }
+        catch {
+            // Directory doesn't exist yet — not an error
+            return [];
+        }
+        const candidates = [];
+        for (const entry of entries) {
+            const dirPath = path.join(this.pluginsDir, entry);
+            let stat;
+            try {
+                stat = await fs.stat(dirPath);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isDirectory())
+                continue;
+            const hasManifest = await this.hasManifestFile(dirPath);
+            if (hasManifest) {
+                candidates.push(dirPath);
+            }
+        }
+        return candidates;
+    }
+    /**
+     * Read and parse the plugin manifest (plugin.yaml or plugin.json).
+     * Validates against PluginManifestSchema.
+     */
+    async loadManifest(pluginDir) {
+        // Try YAML first, then JSON
+        const yamlPath = path.join(pluginDir, "plugin.yaml");
+        const jsonPath = path.join(pluginDir, "plugin.json");
+        let raw;
+        // Attempt YAML
+        const yamlContent = await readFileSafe(yamlPath);
+        if (yamlContent !== null) {
+            try {
+                raw = yaml.load(yamlContent);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Failed to parse plugin.yaml: ${yamlPath} — ${msg}`);
+            }
+        }
+        else {
+            // Attempt JSON
+            const jsonContent = await readFileSafe(jsonPath);
+            if (jsonContent !== null) {
+                try {
+                    raw = JSON.parse(jsonContent);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Failed to parse plugin.json: ${jsonPath} — ${msg}`);
+                }
+            }
+            else {
+                throw new Error(`Manifest file not found (plugin.yaml / plugin.json): ${pluginDir}`);
+            }
+        }
+        const result = PluginManifestSchema.safeParse(raw);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+                .join("\n");
+            throw new ValidationError(`Plugin manifest schema validation failed:\n${issues}`);
+        }
+        return result.data;
+    }
+    /**
+     * Check that the plugin implementation exports all required methods for its type.
+     */
+    validateInterface(type, impl) {
+        const requiredMethods = {
+            adapter: ["execute", "adapterType"],
+            data_source: ["connect", "query", "disconnect", "healthCheck"],
+            notifier: ["name", "notify", "supports"],
+        };
+        const required = requiredMethods[type];
+        for (const method of required) {
+            if (!(method in impl)) {
+                throw new ValidationError(`Plugin is missing required method "${method}" (type: ${type})`);
+            }
+        }
+    }
+    /**
+     * Register the plugin implementation in the appropriate registry.
+     */
+    async registerPlugin(manifest, impl, _pluginDir) {
+        switch (manifest.type) {
+            case "adapter":
+                this.adapterRegistry.register(impl);
+                break;
+            case "data_source":
+                this.dataSourceRegistry.register(impl);
+                break;
+            case "notifier":
+                this.notifierRegistry.register(manifest.name, impl);
+                break;
+        }
+    }
+    // ─── State builders ───
+    buildSuccessState(manifest) {
+        const state = PluginStateSchema.parse({
+            name: manifest.name,
+            manifest,
+            status: "loaded",
+            loaded_at: new Date().toISOString(),
+            trust_score: 0,
+            usage_count: 0,
+            success_count: 0,
+            failure_count: 0,
+        });
+        this.pluginStates.set(manifest.name, state);
+        return state;
+    }
+    buildIncompatibleState(manifest, motivaVersion, range) {
+        const state = PluginStateSchema.parse({
+            name: manifest.name,
+            manifest,
+            status: "incompatible",
+            error_message: `Requires Conatus ${range}, got ${motivaVersion}`,
+            loaded_at: new Date().toISOString(),
+            trust_score: 0,
+            usage_count: 0,
+            success_count: 0,
+            failure_count: 0,
+        });
+        this.pluginStates.set(manifest.name, state);
+        return state;
+    }
+    buildErrorState(pluginDir, reason) {
+        const errorMessage = reason instanceof Error ? reason.message : String(reason);
+        const dirName = path.basename(pluginDir);
+        this.logger?.error(`[PluginLoader] Failed to load plugin: ${pluginDir}\n  ${errorMessage}`);
+        // Build a minimal manifest for the error state
+        const fallbackManifest = PluginManifestSchema.parse({
+            name: sanitizeName(dirName),
+            version: "0.0.0",
+            type: "adapter",
+            capabilities: ["unknown"],
+            description: "(load failed)",
+        });
+        return PluginStateSchema.parse({
+            name: sanitizeName(dirName),
+            manifest: fallbackManifest,
+            status: "error",
+            error_message: errorMessage,
+            loaded_at: new Date().toISOString(),
+            trust_score: 0,
+            usage_count: 0,
+            success_count: 0,
+            failure_count: 0,
+        });
+    }
+    /**
+     * Return the PluginState for a given plugin name, or null if not found.
+     */
+    getPluginState(pluginName) {
+        return this.pluginStates.get(pluginName) ?? null;
+    }
+    /**
+     * Update the in-memory plugin state and persist to disk.
+     */
+    async updatePluginState(pluginName, updates) {
+        const existing = this.pluginStates.get(pluginName);
+        if (existing === undefined) {
+            return;
+        }
+        const updated = PluginStateSchema.parse({ ...existing, ...updates });
+        this.pluginStates.set(pluginName, updated);
+        // Persist to disk: ~/.conatus/plugins/<name>/state.json
+        const statePath = path.join(this.pluginsDir, pluginName, "state.json");
+        await writeJsonFileAtomic(statePath, updated);
+    }
+    // ─── Private helpers ───
+    async hasManifestFile(dirPath) {
+        for (const filename of ["plugin.yaml", "plugin.json"]) {
+            try {
+                await fs.access(path.join(dirPath, filename));
+                return true;
+            }
+            catch {
+                // continue
+            }
+        }
+        return false;
+    }
+}
+// ─── Module-level helpers ───
+// ─── Conatus version (read once from package.json) ───
+let _motivaVersion;
+function getMotivaVersion() {
+    if (_motivaVersion !== undefined)
+        return _motivaVersion;
+    try {
+        const pkgPath = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), "../../package.json");
+        const pkg = JSON.parse(fsSync.readFileSync(pkgPath, "utf-8"));
+        _motivaVersion = pkg.version;
+    }
+    catch {
+        _motivaVersion = "0.0.0";
+    }
+    return _motivaVersion;
+}
+// ─── Semver utilities (no external deps) ───
+export function parseSemver(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        throw new Error(`Invalid semver: ${version}`);
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+export function compareSemver(a, b) {
+    if (a.major !== b.major)
+        return a.major > b.major ? 1 : -1;
+    if (a.minor !== b.minor)
+        return a.minor > b.minor ? 1 : -1;
+    if (a.patch !== b.patch)
+        return a.patch > b.patch ? 1 : -1;
+    return 0;
+}
+export function satisfiesRange(version, min, max) {
+    const v = parseSemver(version);
+    if (min !== undefined && compareSemver(v, parseSemver(min)) < 0)
+        return false;
+    if (max !== undefined && compareSemver(v, parseSemver(max)) > 0)
+        return false;
+    return true;
+}
+/** Read a file and return its content, or null if it doesn't exist. */
+async function readFileSafe(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convert an arbitrary directory name to a valid plugin name.
+ * Replaces invalid characters with hyphens and lowercases the result.
+ */
+function sanitizeName(dirName) {
+    const sanitized = dirName
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/^-+|-+$/g, "") // trim leading/trailing hyphens
+        .replace(/-{2,}/g, "-"); // collapse consecutive hyphens
+    return sanitized || "unknown";
+}
+//# sourceMappingURL=plugin-loader.js.map

package/dist/runtime/plugin-loader.js.map

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

package/dist/satisficing-judge.d.ts

@@ -0,0 +1,113 @@
+import { StateManager } from "./state-manager.js";
+import type { Goal, Dimension } from "./types/goal.js";
+import type { CompletionJudgment, DimensionSatisfaction, IterationConstraints, ThresholdAdjustmentProposal, MappingProposal } from "./types/satisficing.js";
+import type { IEmbeddingClient } from "./embedding-client.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?;
+    constructor(stateManager: StateManager, embeddingClient?: IEmbeddingClient, // Phase 2: for dimension mapping proposals
+    onSatisficingJudgment?: (goalId: string, satisfiedDimensions: 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.
+     */
+    isGoalComplete(goal: Goal): 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>): 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): 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[]): void;
+}
+/**
+ * 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;
+//# sourceMappingURL=satisficing-judge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"satisficing-judge.d.ts","sourceRoot":"","sources":["../src/satisficing-judge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAA0D;gBAG/F,YAAY,EAAE,YAAY,EAC1B,eAAe,CAAC,EAAE,gBAAgB,EAAG,2CAA2C;IAChF,qBAAqB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,KAAK,IAAI;IASjF,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,UAAU;IAalB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAwBtB;;OAEG;IACH,oBAAoB,CAAC,GAAG,EAAE,SAAS,GAAG,qBAAqB;IAsB3D;;;OAGG;IACG,uBAAuB,CAC3B,iBAAiB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EAChE,oBAAoB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAClE,OAAO,CAAC,eAAe,EAAE,CAAC;IAoC7B;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,kBAAkB;IAiD9C;;;OAGG;IACH,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAMxE;;;;;;;OAOG;IACH,4BAA4B,CAC1B,UAAU,EAAE,SAAS,EAAE,EACvB,WAAW,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,EAC7D,WAAW,CAAC,EAAE,oBAAoB,GACjC,MAAM,EAAE;IAwBX;;;;;OAKG;IACH,+BAA+B,CAC7B,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,2BAA2B,EAAE;IA+FhC;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB;IAqEvD;;;;;;;;;;;;OAYG;IACH,0BAA0B,CACxB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,iBAAiB,CAAC,EAAE,OAAO,iBAAiB,EAAE,SAAS,EAAE,GACxD,IAAI;CAuIR;AAID;;;;;;;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"}