conatus 0.1.0

package/dist/observation/observation-engine.d.ts

@@ -0,0 +1,156 @@
+import type { ObservationLogEntry, ObservationLog } from "../types/state.js";
+import type { ObservationLayer, ObservationMethod } from "../types/core.js";
+import type { StateManager } from "../state-manager.js";
+import type { KnowledgeGapSignal } from "../types/knowledge.js";
+import type { IDataSourceAdapter } from "./data-source-adapter.js";
+import type { ILLMClient } from "../llm/llm-client.js";
+import type { Logger } from "../runtime/logger.js";
+import type { TaskDomain } from "../types/pipeline.js";
+import type { AgentTask } from "../execution/adapter-layer.js";
+import type { TaskObservationContext } from "./observation-task.js";
+export type { TaskObservationContext } from "./observation-task.js";
+import { getConfidenceTier, createObservationEntry } from "./observation-helpers.js";
+import type { ObservationEngineOptions } from "./observation-helpers.js";
+export type { ObservationEngineOptions, CrossValidationResult } from "./observation-helpers.js";
+export { applyProgressCeiling, getConfidenceTier, createObservationEntry, needsVerificationTask, resolveContradiction, detectKnowledgeGap, } from "./observation-helpers.js";
+/**
+ * ObservationEngine handles the 3-layer observation architecture.
+ *
+ * Layers (in descending trust order):
+ *   mechanical         — confidence [0.85, 1.0],  progress ceiling 1.00
+ *   independent_review — confidence [0.50, 0.84], progress ceiling 0.90
+ *   self_report        — confidence [0.10, 0.49], progress ceiling 0.70
+ *
+ * Observation logs are persisted via StateManager.appendObservation.
+ * Goal state updates are persisted via StateManager.saveGoal.
+ */
+export declare class ObservationEngine {
+    private readonly stateManager;
+    private dataSources;
+    private readonly llmClient?;
+    private readonly contextProvider?;
+    private readonly options;
+    private readonly logger?;
+    constructor(stateManager: StateManager, dataSources?: IDataSourceAdapter[], llmClient?: ILLMClient, contextProvider?: (goalId: string, dimensionName: string) => Promise<string>, options?: ObservationEngineOptions, logger?: Logger);
+    /**
+     * Compare a mechanical observation value against an LLM-produced value.
+     * Logs a warning when the two diverge beyond the configured threshold.
+     * The mechanical value always wins — LLM is used for diagnostics only.
+     */
+    private crossValidate;
+    /**
+     * Apply progress ceiling based on observation layer.
+     * Returns min(progress, ceiling).
+     */
+    applyProgressCeiling(progress: number, layer: ObservationLayer): number;
+    /**
+     * Return the ConfidenceTier and valid confidence range for a given layer.
+     */
+    getConfidenceTier(layer: ObservationLayer): ReturnType<typeof getConfidenceTier>;
+    /**
+     * Construct a new ObservationLogEntry.
+     * Confidence is clamped to the layer's valid range.
+     */
+    createObservationEntry(params: Parameters<typeof createObservationEntry>[0]): ObservationLogEntry;
+    /**
+     * Returns true when effective progress meets the threshold but confidence
+     * is below 0.85, meaning a mechanical verification task should be generated.
+     */
+    needsVerificationTask(effectiveProgress: number, confidence: number, threshold: number): boolean;
+    /**
+     * Resolve contradictions among multiple observation entries.
+     */
+    resolveContradiction(entries: ObservationLogEntry[]): ObservationLogEntry;
+    /**
+     * Strip trailing _2, _3, ... _N suffixes that LLMs sometimes append to
+     * deduplicate JSON keys.  Only applied to names from external (LLM) input.
+     */
+    normalizeDimensionName(name: string): string;
+    applyObservation(goalId: string, entry: ObservationLogEntry): Promise<void>;
+    /**
+     * Load the observation log for a goal.
+     * Returns an empty log if none exists.
+     */
+    getObservationLog(goalId: string): Promise<ObservationLog>;
+    /**
+     * Persist the observation log for a goal.
+     */
+    saveObservationLog(goalId: string, log: ObservationLog): Promise<void>;
+    /**
+     * Perform an observation pass for all dimensions of a goal.
+     *
+     * For each dimension, the following priority order is used:
+     *   1. DataSource — if a registered data source covers this dimension,
+     *      call observeFromDataSource() (mechanical, confidence 0.90).
+     *   2. LLM — if an LLM client is available, call observeWithLLM()
+     *      (independent_review, confidence 0.70).
+     *   3. self_report — fall back to re-recording the existing stored value.
+     *
+     * @param goalId   The goal to observe.
+     * @param methods  Array of ObservationMethod descriptors (one per dimension,
+     *                 in the same order as goal.dimensions).  Extra entries are
+     *                 ignored; missing entries fall back to the dimension's own
+     *                 observation_method.
+     */
+    observe(goalId: string, methods: ObservationMethod[]): Promise<void>;
+    /**
+     * Observe a goal dimension by querying a registered data source.
+     */
+    observeFromDataSource(goalId: string, dimensionName: string, sourceId: string): Promise<ObservationLogEntry>;
+    /**
+     * Find the first DataSource adapter that can serve the given dimension name.
+     */
+    private findDataSourceForDimension;
+    /**
+     * Observe a goal dimension using the LLM client.
+     *
+     * @param goalId             The goal being observed.
+     * @param dimensionName      The dimension name (snake_case).
+     * @param goalDescription    Human-readable goal description.
+     * @param dimensionLabel     Human-readable dimension label.
+     * @param thresholdDescription  JSON-stringified threshold for context.
+     * @param workspaceContext   Optional pre-fetched workspace context.
+     * @param previousScore      Previous observed score for trend context.
+     * @param dryRun             If true, do not write to state.
+     */
+    observeWithLLM(goalId: string, dimensionName: string, goalDescription: string, dimensionLabel: string, thresholdDescription: string, workspaceContext?: string, previousScore?: number | null, dryRun?: boolean): Promise<ObservationLogEntry>;
+    /**
+     * Return the registered data source adapters.
+     */
+    getDataSources(): IDataSourceAdapter[];
+    /**
+     * Dynamically add a data source adapter at runtime.
+     */
+    addDataSource(adapter: IDataSourceAdapter): void;
+    /**
+     * Dynamically remove a data source adapter at runtime.
+     * Returns true if the adapter was found and removed, false otherwise.
+     */
+    removeDataSource(sourceId: string): boolean;
+    /**
+     * Return dimension info for all registered data sources that expose
+     * getSupportedDimensions().
+     */
+    getAvailableDimensionInfo(): Array<{
+        name: string;
+        dimensions: string[];
+    }>;
+    /**
+     * Detect whether a set of observation entries indicates a knowledge gap.
+     */
+    detectKnowledgeGap(entries: ObservationLogEntry[], dimensionName?: string): KnowledgeGapSignal | null;
+    /**
+     * Collect domain-specific pre-execution context for a task.
+     *
+     * Delegates to the standalone `_observeForTask` function from
+     * `observation-task.ts`. The `contextProvider` on this class returns
+     * `Promise<string>` while `ObserveForTaskDeps` expects
+     * `Promise<string | null>`, so we adapt inline (both are compatible at
+     * runtime since `string` satisfies `string | null`).
+     *
+     * @param task    The agent task requiring pre-execution context.
+     * @param domain  The task domain that governs the collection strategy.
+     */
+    observeForTask(task: AgentTask, domain: TaskDomain): Promise<TaskObservationContext>;
+}
+//# sourceMappingURL=observation-engine.d.ts.map

package/dist/observation/observation-engine.d.ts.map

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

package/dist/observation/observation-engine.js

@@ -0,0 +1,359 @@
+import { ObservationLogSchema } from "../types/state.js";
+import { observeForTask as _observeForTask, } from "./observation-task.js";
+import { applyProgressCeiling, getConfidenceTier, createObservationEntry, needsVerificationTask, resolveContradiction, normalizeDimensionName, detectKnowledgeGap, loadOrEmptyObservationLog, } from "./observation-helpers.js";
+import { observeWithLLM as llmObserve } from "./observation-llm.js";
+import { applyObservation as applyObservationFn, observeFromDataSource as observeFromDataSourceFn, } from "./observation-apply.js";
+export { applyProgressCeiling, getConfidenceTier, createObservationEntry, needsVerificationTask, resolveContradiction, detectKnowledgeGap, } from "./observation-helpers.js";
+/**
+ * ObservationEngine handles the 3-layer observation architecture.
+ *
+ * Layers (in descending trust order):
+ *   mechanical         — confidence [0.85, 1.0],  progress ceiling 1.00
+ *   independent_review — confidence [0.50, 0.84], progress ceiling 0.90
+ *   self_report        — confidence [0.10, 0.49], progress ceiling 0.70
+ *
+ * Observation logs are persisted via StateManager.appendObservation.
+ * Goal state updates are persisted via StateManager.saveGoal.
+ */
+export class ObservationEngine {
+    stateManager;
+    dataSources;
+    llmClient;
+    contextProvider;
+    options;
+    logger;
+    constructor(stateManager, dataSources = [], llmClient, contextProvider, options = {}, logger) {
+        this.stateManager = stateManager;
+        this.dataSources = dataSources;
+        this.llmClient = llmClient;
+        this.contextProvider = contextProvider;
+        this.options = options;
+        this.logger = logger;
+    }
+    // ─── Cross-Validation ───
+    /**
+     * Compare a mechanical observation value against an LLM-produced value.
+     * Logs a warning when the two diverge beyond the configured threshold.
+     * The mechanical value always wins — LLM is used for diagnostics only.
+     */
+    crossValidate(goalId, dimensionName, mechanicalValue, llmValue) {
+        const threshold = this.options.divergenceThreshold ?? 0.20;
+        const denominator = Math.max(Math.abs(mechanicalValue), Math.abs(llmValue), 1);
+        const ratio = Math.abs(mechanicalValue - llmValue) / denominator;
+        const diverged = ratio > threshold;
+        if (diverged) {
+            this.logger?.warn(`[CrossValidation] DIVERGED goal="${goalId}" dim="${dimensionName}" ` +
+                `mechanical=${mechanicalValue} llm=${llmValue} ` +
+                `ratio=${ratio.toFixed(3)} threshold=${threshold} resolution=mechanical_wins`);
+        }
+        return {
+            dimensionName,
+            mechanicalValue,
+            llmValue,
+            diverged,
+            divergenceRatio: ratio,
+            resolution: "mechanical_wins",
+        };
+    }
+    // ─── Progress Ceiling ───
+    /**
+     * Apply progress ceiling based on observation layer.
+     * Returns min(progress, ceiling).
+     */
+    applyProgressCeiling(progress, layer) {
+        return applyProgressCeiling(progress, layer);
+    }
+    // ─── Confidence Tier ───
+    /**
+     * Return the ConfidenceTier and valid confidence range for a given layer.
+     */
+    getConfidenceTier(layer) {
+        return getConfidenceTier(layer);
+    }
+    // ─── Create Observation Entry ───
+    /**
+     * Construct a new ObservationLogEntry.
+     * Confidence is clamped to the layer's valid range.
+     */
+    createObservationEntry(params) {
+        return createObservationEntry(params);
+    }
+    // ─── Evidence Gate ───
+    /**
+     * Returns true when effective progress meets the threshold but confidence
+     * is below 0.85, meaning a mechanical verification task should be generated.
+     */
+    needsVerificationTask(effectiveProgress, confidence, threshold) {
+        return needsVerificationTask(effectiveProgress, confidence, threshold);
+    }
+    // ─── Contradiction Resolution ───
+    /**
+     * Resolve contradictions among multiple observation entries.
+     */
+    resolveContradiction(entries) {
+        return resolveContradiction(entries);
+    }
+    // ─── Dimension Name Normalization ───
+    /**
+     * Strip trailing _2, _3, ... _N suffixes that LLMs sometimes append to
+     * deduplicate JSON keys.  Only applied to names from external (LLM) input.
+     */
+    normalizeDimensionName(name) {
+        return normalizeDimensionName(name, this.logger);
+    }
+    // ─── Apply Observation to Goal ───
+    applyObservation(goalId, entry) {
+        return applyObservationFn(goalId, entry, this.stateManager, this.options);
+    }
+    // ─── Observation Log Persistence ───
+    /**
+     * Load the observation log for a goal.
+     * Returns an empty log if none exists.
+     */
+    async getObservationLog(goalId) {
+        return loadOrEmptyObservationLog(this.stateManager, goalId);
+    }
+    /**
+     * Persist the observation log for a goal.
+     */
+    async saveObservationLog(goalId, log) {
+        if (goalId !== log.goal_id)
+            throw new Error("goalId mismatch");
+        const parsed = ObservationLogSchema.parse(log);
+        await this.stateManager.saveObservationLog(parsed);
+    }
+    // ─── Observe ───
+    /**
+     * Perform an observation pass for all dimensions of a goal.
+     *
+     * For each dimension, the following priority order is used:
+     *   1. DataSource — if a registered data source covers this dimension,
+     *      call observeFromDataSource() (mechanical, confidence 0.90).
+     *   2. LLM — if an LLM client is available, call observeWithLLM()
+     *      (independent_review, confidence 0.70).
+     *   3. self_report — fall back to re-recording the existing stored value.
+     *
+     * @param goalId   The goal to observe.
+     * @param methods  Array of ObservationMethod descriptors (one per dimension,
+     *                 in the same order as goal.dimensions).  Extra entries are
+     *                 ignored; missing entries fall back to the dimension's own
+     *                 observation_method.
+     */
+    async observe(goalId, methods) {
+        const goal = await this.stateManager.loadGoal(goalId);
+        if (goal === null) {
+            throw new Error(`observe: goal "${goalId}" not found`);
+        }
+        // When methods array is non-empty, only observe the dimensions corresponding to
+        // the provided methods (the caller is explicitly selecting which dimensions to observe).
+        // When methods is empty (e.g. CoreLoop passes []), observe all dimensions.
+        const observeCount = methods.length > 0 ? methods.length : goal.dimensions.length;
+        // Workspace context for LLM observations — fetched lazily per dimension, cached within
+        // this observe() call to avoid re-reading the same files for multiple dimensions.
+        const contextCache = new Map();
+        let warnedNoProvider = false;
+        const fetchWorkspaceContext = async (gId, dimensionName) => {
+            const cacheKey = `${gId}::${dimensionName}`;
+            if (contextCache.has(cacheKey))
+                return contextCache.get(cacheKey);
+            if (this.contextProvider) {
+                try {
+                    const ctx = await this.contextProvider(gId, dimensionName);
+                    contextCache.set(cacheKey, ctx);
+                    return ctx;
+                }
+                catch (err) {
+                    this.logger?.warn(`[ObservationEngine] contextProvider failed: ${err instanceof Error ? err.message : String(err)}. LLM observation will proceed without workspace context.`);
+                }
+            }
+            else {
+                if (!warnedNoProvider) {
+                    warnedNoProvider = true;
+                    this.logger?.warn(`[ObservationEngine] No contextProvider configured. LLM observation will proceed without workspace context (scores may be unreliable).`);
+                }
+            }
+            return undefined;
+        };
+        for (let idx = 0; idx < observeCount; idx++) {
+            const dim = goal.dimensions[idx];
+            const method = methods[idx] ?? dim.observation_method;
+            // 1. Try DataSource first
+            const dataSource = this.findDataSourceForDimension(dim.name, goalId);
+            if (dataSource) {
+                try {
+                    await this.observeFromDataSource(goalId, dim.name, dataSource.sourceId);
+                    // Cross-validation: also run LLM and compare (for logging/diagnostics only)
+                    if (this.options.crossValidationEnabled && this.llmClient) {
+                        try {
+                            const updatedGoal = await this.stateManager.loadGoal(goalId);
+                            const dimState = updatedGoal?.dimensions.find((d) => d.name === dim.name);
+                            const mechanicalValue = typeof dimState?.current_value === "number" ? dimState.current_value : 0;
+                            const ctx = await fetchWorkspaceContext(goalId, dim.name);
+                            const llmEntry = await this.observeWithLLM(goalId, dim.name, goal.description, dim.label ?? dim.name, JSON.stringify(dim.threshold), ctx, mechanicalValue, true // dryRun — do NOT write to state
+                            );
+                            const llmValue = typeof llmEntry.extracted_value === "number" ? llmEntry.extracted_value : 0;
+                            this.crossValidate(goalId, dim.name, mechanicalValue, llmValue);
+                        }
+                        catch (err) {
+                            this.logger?.warn(`[CrossValidation] LLM comparison failed for "${dim.name}": ${err}`);
+                        }
+                    }
+                    continue;
+                }
+                catch (err) {
+                    this.logger?.warn(`[ObservationEngine] DataSource observation failed for dimension "${dim.name}" (source: ${dataSource.sourceId}): ${err instanceof Error ? err.message : String(err)}. Falling through to LLM fallback.`);
+                }
+            }
+            // 2. Try LLM if available
+            if (this.llmClient) {
+                const ctx = await fetchWorkspaceContext(goalId, dim.name);
+                try {
+                    // Only pass previousScore when there's actual observation history.
+                    // The seed current_value in a new goal is not a real observation and
+                    // should not trigger the §3.3 score-jump suppression guard.
+                    const hasPriorObs = Array.isArray(dim.history) && dim.history.length > 0;
+                    await this.observeWithLLM(goalId, dim.name, goal.description, dim.label ?? dim.name, JSON.stringify(dim.threshold), ctx, hasPriorObs && typeof dim.current_value === "number" ? dim.current_value : null);
+                    continue;
+                }
+                catch (err) {
+                    this.logger?.warn(`[ObservationEngine] LLM observation failed for dimension "${dim.name}": ${err instanceof Error ? err.message : String(err)}. Falling back to self_report.`);
+                }
+            }
+            else if (this.dataSources.length > 0) {
+                // DataSources exist but none match this dimension and no LLM client
+                this.logger?.warn(`[ObservationEngine] Warning: dimension "${dim.name}" has no matching DataSource and no LLM client available for observation`);
+            }
+            // 3. Fall back to self_report
+            const entry = createObservationEntry({
+                goalId,
+                dimensionName: dim.name,
+                layer: "self_report",
+                method,
+                trigger: "periodic",
+                rawResult: dim.current_value,
+                extractedValue: typeof dim.current_value === "number" ||
+                    typeof dim.current_value === "string" ||
+                    typeof dim.current_value === "boolean" ||
+                    dim.current_value === null
+                    ? dim.current_value
+                    : null,
+                confidence: dim.confidence,
+            });
+            await this.applyObservation(goalId, entry);
+        }
+    }
+    // ─── Data Source Observation ───
+    /**
+     * Observe a goal dimension by querying a registered data source.
+     */
+    async observeFromDataSource(goalId, dimensionName, sourceId) {
+        return observeFromDataSourceFn(goalId, dimensionName, sourceId, this.dataSources, (gId, entry) => this.applyObservation(gId, entry));
+    }
+    // ─── DataSource Dimension Lookup ───
+    /**
+     * Find the first DataSource adapter that can serve the given dimension name.
+     */
+    findDataSourceForDimension(dimensionName, goalId) {
+        const matches = (ds) => {
+            const dims = ds.getSupportedDimensions?.() ?? [];
+            if (dims.includes(dimensionName))
+                return true;
+            if (ds.config?.dimension_mapping && dimensionName in ds.config.dimension_mapping)
+                return true;
+            return false;
+        };
+        // First pass: prefer a datasource explicitly scoped to this goalId
+        for (const ds of this.dataSources) {
+            const scopeGoalId = ds.config?.scope_goal_id;
+            if (scopeGoalId === goalId && goalId !== undefined && matches(ds))
+                return ds;
+        }
+        // Second pass: fall back to an unscoped datasource
+        for (const ds of this.dataSources) {
+            const scopeGoalId = ds.config?.scope_goal_id;
+            if (scopeGoalId === undefined && matches(ds))
+                return ds;
+        }
+        return null;
+    }
+    // ─── LLM Observation ───
+    /**
+     * Observe a goal dimension using the LLM client.
+     *
+     * @param goalId             The goal being observed.
+     * @param dimensionName      The dimension name (snake_case).
+     * @param goalDescription    Human-readable goal description.
+     * @param dimensionLabel     Human-readable dimension label.
+     * @param thresholdDescription  JSON-stringified threshold for context.
+     * @param workspaceContext   Optional pre-fetched workspace context.
+     * @param previousScore      Previous observed score for trend context.
+     * @param dryRun             If true, do not write to state.
+     */
+    async observeWithLLM(goalId, dimensionName, goalDescription, dimensionLabel, thresholdDescription, workspaceContext, previousScore, dryRun) {
+        if (!this.llmClient) {
+            throw new Error("observeWithLLM: llmClient is not configured");
+        }
+        return llmObserve(goalId, dimensionName, goalDescription, dimensionLabel, thresholdDescription, this.llmClient, this.options, (gId, entry) => this.applyObservation(gId, entry), workspaceContext, previousScore, dryRun, this.logger);
+    }
+    /**
+     * Return the registered data source adapters.
+     */
+    getDataSources() {
+        return this.dataSources;
+    }
+    /**
+     * Dynamically add a data source adapter at runtime.
+     */
+    addDataSource(adapter) {
+        this.dataSources.push(adapter);
+    }
+    /**
+     * Dynamically remove a data source adapter at runtime.
+     * Returns true if the adapter was found and removed, false otherwise.
+     */
+    removeDataSource(sourceId) {
+        const index = this.dataSources.findIndex((ds) => ds.sourceId === sourceId);
+        if (index === -1) {
+            return false;
+        }
+        this.dataSources.splice(index, 1);
+        return true;
+    }
+    /**
+     * Return dimension info for all registered data sources that expose
+     * getSupportedDimensions().
+     */
+    getAvailableDimensionInfo() {
+        const result = [];
+        for (const ds of this.dataSources) {
+            if (typeof ds.getSupportedDimensions === "function") {
+                result.push({ name: ds.config.name, dimensions: ds.getSupportedDimensions() });
+            }
+        }
+        return result;
+    }
+    // ─── Knowledge Gap Detection ───
+    /**
+     * Detect whether a set of observation entries indicates a knowledge gap.
+     */
+    detectKnowledgeGap(entries, dimensionName) {
+        return detectKnowledgeGap(entries, dimensionName);
+    }
+    // ─── Task-Scoped Observation ───
+    /**
+     * Collect domain-specific pre-execution context for a task.
+     *
+     * Delegates to the standalone `_observeForTask` function from
+     * `observation-task.ts`. The `contextProvider` on this class returns
+     * `Promise<string>` while `ObserveForTaskDeps` expects
+     * `Promise<string | null>`, so we adapt inline (both are compatible at
+     * runtime since `string` satisfies `string | null`).
+     *
+     * @param task    The agent task requiring pre-execution context.
+     * @param domain  The task domain that governs the collection strategy.
+     */
+    async observeForTask(task, domain) {
+        return _observeForTask({ contextProvider: this.contextProvider, logger: this.logger }, task, domain);
+    }
+}
+//# sourceMappingURL=observation-engine.js.map

package/dist/observation/observation-engine.js.map

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

package/dist/observation/observation-helpers.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import type { ObservationLogEntry, ObservationLog } from "../types/state.js";
+import type { ObservationLayer, ObservationMethod, ObservationTrigger, ConfidenceTier } from "../types/core.js";
+import type { KnowledgeGapSignal } from "../types/knowledge.js";
+import type { VectorIndex } from "../knowledge/vector-index.js";
+import type { Logger } from "../runtime/logger.js";
+export interface ObservationEngineOptions {
+    crossValidationEnabled?: boolean;
+    divergenceThreshold?: number;
+    /** Injectable override for git diff context (used in tests). */
+    gitContextFetcher?: (maxChars: number) => string | Promise<string>;
+    /** Optional VectorIndex for indexing dimension names after observation. */
+    vectorIndex?: VectorIndex;
+}
+export interface CrossValidationResult {
+    dimensionName: string;
+    mechanicalValue: number;
+    llmValue: number;
+    diverged: boolean;
+    divergenceRatio: number;
+    resolution: "mechanical_wins";
+}
+interface LayerConfig {
+    ceiling: number;
+    tier: ConfidenceTier;
+    range: [number, number];
+}
+export declare const LAYER_CONFIG: Record<ObservationLayer, LayerConfig>;
+export declare const LAYER_PRIORITY: Record<ObservationLayer, number>;
+export declare const LLMObservationResponseSchema: z.ZodObject<{
+    score: z.ZodNumber;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    score: number;
+    reason: string;
+}, {
+    score: number;
+    reason: string;
+}>;
+/**
+ * Apply progress ceiling based on observation layer.
+ * Returns min(progress, ceiling).
+ */
+export declare function applyProgressCeiling(progress: number, layer: ObservationLayer): number;
+/**
+ * Return the ConfidenceTier and valid confidence range for a given layer.
+ */
+export declare function getConfidenceTier(layer: ObservationLayer): {
+    tier: ConfidenceTier;
+    range: [number, number];
+};
+/**
+ * Construct a new ObservationLogEntry.
+ * Confidence is clamped to the layer's valid range.
+ */
+export declare function createObservationEntry(params: {
+    goalId: string;
+    dimensionName: string;
+    layer: ObservationLayer;
+    method: ObservationMethod;
+    trigger: ObservationTrigger;
+    rawResult: unknown;
+    extractedValue: number | string | boolean | null;
+    confidence: number;
+    notes?: string;
+}): ObservationLogEntry;
+/**
+ * Returns true when effective progress meets the threshold but confidence
+ * is below 0.85, meaning a mechanical verification task should be generated.
+ */
+export declare function needsVerificationTask(effectiveProgress: number, confidence: number, threshold: number): boolean;
+/**
+ * Resolve contradictions among multiple observation entries.
+ *
+ * Resolution rules:
+ *   1. Higher-priority layer wins (mechanical > independent_review > self_report).
+ *   2. Within the same layer, take the pessimistic (lower) numeric value.
+ *   3. For non-numeric values, take the first entry in the winning layer.
+ *
+ * Returns the single "winning" entry.
+ * Throws if entries array is empty.
+ */
+export declare function resolveContradiction(entries: ObservationLogEntry[]): ObservationLogEntry;
+/**
+ * Strip trailing _2, _3, ... _N suffixes that LLMs sometimes append to
+ * deduplicate JSON keys.  Only applied to names from external (LLM) input.
+ *
+ * Examples:
+ *   "todo_count_2"  → "todo_count"
+ *   "quality_3"     → "quality"
+ *   "step_count"    → "step_count"  (trailing token is not a digit-only suffix)
+ *   "coverage"      → "coverage"
+ */
+export declare function normalizeDimensionName(name: string, logger?: Logger): string;
+/**
+ * Detect whether a set of observation entries indicates a knowledge gap.
+ *
+ * Rule: if ALL entries have confidence < 0.3, interpretation is too
+ * uncertain — emit an `interpretation_difficulty` signal.
+ *
+ * Returns null when confidence is sufficient (no gap detected).
+ */
+export declare function detectKnowledgeGap(entries: ObservationLogEntry[], dimensionName?: string): KnowledgeGapSignal | null;
+/**
+ * Load the observation log for a goal, returning an empty log if none exists.
+ * Pure function — requires stateManager passed in.
+ */
+export declare function loadOrEmptyObservationLog(stateManager: {
+    loadObservationLog: (goalId: string) => Promise<ObservationLog | null>;
+}, goalId: string): Promise<ObservationLog>;
+export {};
+//# sourceMappingURL=observation-helpers.d.ts.map

package/dist/observation/observation-helpers.d.ts.map

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