pulseed 0.1.4 → 0.1.5

package/dist/observation-engine.d.ts

@@ -1,218 +0,0 @@
-import type { ObservationLogEntry, ObservationLog } from "./types/state.js";
-import type { ObservationLayer, ObservationMethod, ObservationTrigger, ConfidenceTier } 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";
-export interface ObservationEngineOptions {
-    crossValidationEnabled?: boolean;
-    divergenceThreshold?: number;
-    /** Injectable override for git diff context (used in tests). */
-    gitContextFetcher?: (maxChars: number) => string;
-}
-export interface CrossValidationResult {
-    dimensionName: string;
-    mechanicalValue: number;
-    llmValue: number;
-    diverged: boolean;
-    divergenceRatio: number;
-    resolution: "mechanical_wins";
-}
-/**
- * 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;
-    constructor(stateManager: StateManager, dataSources?: IDataSourceAdapter[], llmClient?: ILLMClient, contextProvider?: (goalId: string, dimensionName: string) => Promise<string>, options?: ObservationEngineOptions);
-    /**
-     * 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): {
-        tier: ConfidenceTier;
-        range: [number, number];
-    };
-    /**
-     * Construct a new ObservationLogEntry.
-     * Confidence is clamped to the layer's valid range.
-     */
-    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.
-     */
-    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.
-     */
-    resolveContradiction(entries: ObservationLogEntry[]): ObservationLogEntry;
-    /**
-     * Apply an observation entry to the corresponding goal dimension.
-     *
-     * Steps:
-     *   1. Load goal via StateManager.
-     *   2. Find dimension by name.
-     *   3. Update current_value and confidence.
-     *   4. Append to dimension history.
-     *   5. Persist observation log entry via StateManager.appendObservation.
-     *   6. Persist updated goal via StateManager.saveGoal.
-     */
-    /**
-     * 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"
-     */
-    private normalizeDimensionName;
-    applyObservation(goalId: string, entry: ObservationLogEntry): void;
-    /**
-     * Load the observation log for a goal.
-     * Returns an empty log if none exists.
-     */
-    getObservationLog(goalId: string): ObservationLog;
-    /**
-     * Persist the observation log for a goal.
-     */
-    saveObservationLog(goalId: string, log: ObservationLog): 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.
-     *
-     * Steps:
-     *   1. Find the data source by sourceId.
-     *   2. Build a DataSourceQuery, using dimension_mapping if configured.
-     *   3. Call source.query().
-     *   4. Convert result value to numeric if possible.
-     *   5. Create and persist an ObservationLogEntry.
-     *   6. Return the entry.
-     */
-    observeFromDataSource(goalId: string, dimensionName: string, sourceId: string): Promise<ObservationLogEntry>;
-    /**
-     * Find the first DataSource adapter that can serve the given dimension name.
-     * Checks both getSupportedDimensions() and dimension_mapping config keys.
-     * Returns null if no adapter matches.
-     */
-    private findDataSourceForDimension;
-    /**
-     * Fetch a concise workspace context via git diff when no contextProvider is available.
-     * Returns an empty string if git commands fail (e.g., not a git repo).
-     *
-     * Uses execFileSync (not exec/execSync) to avoid shell-injection risks.
-     *
-     * @param maxChars  Maximum characters to return (default: 3000).
-     */
-    private fetchGitDiffContext;
-    /**
-     * Observe a goal dimension using the LLM client.
-     *
-     * The LLM is asked to score the dimension from 0.0 to 1.0.
-     * The score is used as extractedValue, and confidence is fixed at 0.70
-     * (middle of the independent_review range [0.50, 0.84]).
-     *
-     * If workspaceContext is not provided, a git diff fallback is attempted
-     * so the LLM has actual evidence to evaluate. If that also fails,
-     * the prompt includes an explicit warning and the LLM must score 0.0.
-     *
-     * @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.
-     * The adapter becomes immediately available for subsequent observe() calls.
-     */
-    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.
-     *
-     * 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).
-     */
-    detectKnowledgeGap(entries: ObservationLogEntry[], dimensionName?: string): KnowledgeGapSignal | null;
-}
-//# sourceMappingURL=observation-engine.d.ts.map

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

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