@jmtrin/opencode-kevin 1.2.0 → 1.4.0

package/dist/plugin/MemoryService.d.ts

@@ -1,360 +0,0 @@
-import type { Store } from "./Store.js";
-import type { Metrics } from "./metrics.js";
-export type MemoryType = "error" | "pattern" | "decision" | "context" | "rule" | "solution";
-export type MemoryScope = "project" | "session";
-export type MemoryOrigin = "reflector" | "agent" | "pattern" | "retrospective" | "causal" | "imported";
-export interface Memory {
-    id: string;
-    type: MemoryType;
-    content: string;
-    scope: MemoryScope;
-    relevanceScore: number;
-    sourceTool?: string | null;
-    sourceSession?: string | null;
-    metadata?: Record<string, unknown> | null;
-    createdAt: string;
-    updatedAt: string;
-    expiresAt?: string | null;
-    /** v0.2.0 — project the memory belongs to (nullable for legacy rows). */
-    projectId?: string | null;
-    /** v0.2.0 — content fingerprint for dedup (only set for `type='error'`). */
-    fingerprint?: string | null;
-    /** v0.2.0 — origin of the memory. */
-    origin?: MemoryOrigin | null;
-    /** v0.3.0 — confidence derived from causal evidence (0..1). Only set by CausalChain. */
-    confidence?: number | null;
-    /** v0.3.0 — number of confirmed causal fix confirmations. */
-    evidenceCount?: number | null;
-    /** v0.3.0 — last time causal evidence was observed. */
-    lastVerifiedAt?: string | null;
-    /** v0.3.0 — lifecycle status. Default 'active'. */
-    status?: string | null;
-    /** v0.4.0 — deterministic capture of the linked fix call (K4-014). */
-    fixArgs?: string | null;
-    /** v0.4.0 (BUG-008/010) — negative evidence: how many times the
-     * fingerprint recurred after injection (demotes confidence). */
-    recurrenceCount?: number | null;
-    /** v0.5.0 (K5-009 / plan §5.3, D5-07) — human verdict: ignored memories
-     * are excluded from retrieval and injection. */
-    ignored?: boolean;
-    /** v0.5.0 (K5-009 / plan §5.3) — id of the memory that superseded this
-     * one (decision/rule replacement, K3-014). Null when active. */
-    supersedes?: string | null;
-    /** v0.5.0 (K5-010 / plan §5.3, D5-02) — human judgement counters,
-     * folded into confidence by computeConfidence. */
-    feedbackPositive?: number;
-    /** v0.6.0 (K6-011 / plan §5.4) — curation state: curated memories have
-     * been written to AGENTS.md and are excluded from new candidates. */
-    curated?: boolean;
-    /** v0.6.0 (K6-011 / plan §5.4) — when the memory was curated (ISO time). */
-    curatedAt?: string | null;
-    /** v0.6.0 (K6-011 / plan §5.3) — deterministic inferability verdict from
-     * `inferability.classify()`; `null` = unknown, never collapsed. */
-    inferable?: "inferable" | "non_inferable" | null;
-    /** v0.5.0 (K5-010 / plan §5.3, D5-02) — human judgement counters,
-     * folded into confidence by computeConfidence. */
-    feedbackNegative?: number;
-    /** v0.7.0 (K7-008 / plan §5.3, D7-03) — de-ranking penalty in
-     * [0, 0.5], clamped by applyTruthPenalty. Multiplies rankScore as
-     * `(1 - truthPenalty)`. Defaults to 0. */
-    truthPenalty?: number | null;
-    /** v0.7.0 (K7-008 / plan §5.3, D7-03) — first contradiction timestamp. */
-    contradictedAt?: string | null;
-    /** v0.8.0 (K8-018 / plan §5.2) — the memory's layer marker: 'local'
-     * (default) or 'shared'. */
-    layer?: string | null;
-}
-/**
- * v0.8.0 (K8-018 / plan §5.2) — outcome of `update()`. A refusal is a
- * typed value, never a throw and never a silent no-op.
- */
-export type MemoryUpdateResult = {
-    ok: true;
-} | {
-    ok: false;
-    refused: readonly string[];
-};
-export interface SaveInput {
-    type: MemoryType;
-    content: string;
-    /** v0.4.0 (BUG-008) — preserve the original id on okf import;
-     * when absent a fresh uuidv7 is generated. */
-    id?: string;
-    scope?: MemoryScope;
-    relevanceScore?: number;
-    sourceTool?: string;
-    sourceSession?: string;
-    metadata?: Record<string, unknown>;
-    expiresAt?: string;
-    /** v0.2.0 — project id. When absent, the memory is cross-project (NULL project_id). */
-    projectId?: string;
-    /** v0.2.0 — origin. Defaults to `'agent'` when omitted. */
-    origin?: MemoryOrigin;
-    /** v0.2.0 — explicit fingerprint. Auto-derived for `type='error'` if absent. */
-    fingerprint?: string;
-    /** v0.3.0 — number of confirmed causal fix confirmations. */
-    evidenceCount?: number;
-    /** v0.3.0 — last time causal evidence was observed. */
-    lastVerifiedAt?: string;
-    /** v0.3.0 — lifecycle status. Default 'active'. */
-    status?: string;
-    /** v0.4.0 (BUG-008/010) — how many times the fingerprint recurred
-     * after injection (negative evidence, demotes confidence). */
-    recurrenceCount?: number;
-}
-export interface QueryInput {
-    text: string;
-    type?: string;
-    scope?: MemoryScope | "all";
-    limit?: number;
-    /** v0.2.0 — when true, returns full `Memory` rows (v0.1.x behavior).
-     * When `false` or absent, returns `SlimMemory` rows (default v0.2.0
-     * behavior, per plan §B6.3 / K2-010).
-     */
-    full?: boolean;
-    /** v0.3.0 — when true, includes rows where status = 'superseded'.
-     * Default false (only active rows). */
-    includeSuperseded?: boolean;
-    /** v0.3.0 (BUG-001) — when true, the slim payload also carries
-     * `confidence`, `evidence_count` and `last_verified_at` (v0.3.0 K3
-     * evidence fields). Default false (minimal slim shape). */
-    evidence?: boolean;
-}
-/** v0.2.0 — slim query payload (K2-010). Snippet is a short content prefix;
- * `score` is the FTS5 BM25 score when available, falling back to
- * `relevanceScore` for non-FTS callers. */
-export interface SlimMemory {
-    id: string;
-    type: MemoryType;
-    scope: MemoryScope;
-    score: number;
-    snippet: string;
-}
-/** v0.3.0 (BUG-001) — slim payload extended with the evidence fields when
- * `query({ evidence: true })`. Fills the `kevin_query(evidence: true)`
- * contract without falling back to the full `Memory` shape. */
-export interface SlimMemoryWithEvidence extends SlimMemory {
-    confidence: number | null;
-    evidence_count: number | null;
-    last_verified_at: string | null;
-}
-export interface GetRelevantInput {
-    query?: string;
-    maxTokens?: number;
-    scope?: MemoryScope | "all";
-    /** v0.3.0 — when true, includes rows where status = 'superseded'.
-     * Default false (only active rows). */
-    includeSuperseded?: boolean;
-    /**
-     * v0.4.0 (BUG-016) — when false, the relevance bump (K2-023) is
-     * skipped. Used by ContextInjector's probe fetch so the decision and
-     * any retry both see the ORIGINAL ranking; the single bump is applied
-     * by the fetch that actually produces the injected block.
-     */
-    bump?: boolean;
-    /**
-     * v0.5.0 (K5-008 / plan §5.6, D5-10) — injectable clock. Defaults to
-     * `new Date()` at the top of the method and is the ONLY time source
-     * for recency decay: replay and tests can freeze time. Never call
-     * `Date.now()` again inside the method.
-     */
-    now?: Date;
-}
-interface MemoryRow {
-    id: string;
-    type: MemoryType;
-    content: string;
-    scope: MemoryScope;
-    relevance_score: number;
-    source_tool: string | null;
-    source_session: string | null;
-    metadata: string | null;
-    created_at: string;
-    updated_at: string;
-    expires_at: string | null;
-    /** v0.2.0 columns — nullable for rows from pre-003 DBs. */
-    project_id?: string | null;
-    fingerprint?: string | null;
-    origin?: MemoryOrigin | null;
-    /** v0.3.0 */
-    evidence_count?: number;
-    last_verified_at?: string | null;
-    status?: string;
-    /** v0.4.0 */
-    recurrence_count?: number;
-    /** v0.4.0 */
-    fix_args?: string | null;
-    /** v0.5.0 (K5-009) */
-    ignored?: number;
-    /** v0.5.0 (K5-009) */
-    superseded_by?: string | null;
-    /** v0.5.0 (K5-010) */
-    feedback_positive?: number;
-    /** v0.5.0 (K5-010) */
-    feedback_negative?: number;
-    /** v0.6.0 (K6-011 / migration 007) */
-    curated?: number;
-    /** v0.6.0 (K6-011 / migration 007) */
-    curated_at?: string | null;
-    /** v0.6.0 (K6-011 / migration 007) — 1 = inferable, 0 = non_inferable,
-     * NULL = unknown. */
-    inferable?: number | null;
-    /** v0.7.0 (K7-008 / migration 008) — de-ranking penalty in [0, 0.5]. */
-    truth_penalty?: number | null;
-    /** v0.7.0 (K7-008 / migration 008) — first contradiction timestamp. */
-    contradicted_at?: string | null;
-    /** v0.8.0 (K8-018 / migration 009) — layer marker on the row. */
-    layer?: string | null;
-}
-export declare const DATE_NOW = "2099-01-01T00:00:00.000Z";
-export declare function hasRepoIdColumn(store: Store): boolean;
-export declare function mapRow(row: MemoryRow, score?: number): Memory;
-export declare class MemoryService {
-    private readonly metrics;
-    constructor(store: Store, metrics?: Metrics | null, repoId?: string | null);
-    private store;
-    private repoId;
-    setRepoId(repoId: string | null): void;
-    private hasRecurrenceColumn;
-    private hasIgnoredColumn;
-    private hasCuratedColumn;
-    private hasTruthColumns;
-    private hasRepoIdColumn;
-    save(input: SaveInput): string;
-    /**
-     * v0.6.0 (K6-011 / plan §5.4) — mark memories as curated. Batch in a
-     * single statement with an `IN` clause; do not loop. Returns the number
-     * of rows matched by the statement (not only rows whose value changed):
-     * a second call with the same ids re-matches them, so the caller must
-     * re-filter the id list (e.g. by `curated = 0`) to observe 0.
-     */
-    markCurated(ids: readonly string[], at: string): number;
-    getById(id: string): Memory | null;
-    /**
-     * v0.4.0 (K4-016) — most recent ACTIVE memory for a fingerprint,
-     * optionally filtered by type. Feeds the HITL suggestion lookup
-     * (most-recurred fingerprint → its pattern memory).
-     */
-    getByFingerprint(fingerprint: string, type?: MemoryType): Memory | null;
-    /**
-     * v0.8.0 (K8-018 / plan §5.2) — result of a memory mutation.
-     * `refused` lists the shared-layer columns that were not written.
-     */
-    update(id: string, fields: Partial<Memory>): MemoryUpdateResult;
-    /**
-     * v0.8.0 (K8-018 / plan §5.2) — count a refused shared-row write. The
-     * key lives OUTSIDE the frozen METRIC_KEYS ladder (K7-004), following
-     * the v0.6.0 `incrRegistered` precedent: it persists to the same
-     * `kevin_metrics` table and is read back by `kevin_audit` as a bare SQL
-     * scalar, so the counter survives across processes without growing the
-     * 39-key ladder.
-     */
-    private countSharedRefusal;
-    /**
-     * v0.7.0 (K7-008 / plan §5.3, D7-03) — apply a bounded truth penalty.
-     * Clamps `penalty` to [0, 0.5], writes `truth_penalty` and `contradicted_at`,
-     * and increments `memories_contradicted` ONLY when the value moves from 0
-     * to non-zero (a second penalty on the same memory does not re-count).
-     * It NEVER writes `status` — contradiction de-ranks; it never deletes
-     * (Principle 24). `reason` is the human-readable explanation surfaced by
-     * `kevin_facts`; the caller persists it in the `memory_conflicts` row.
-     */
-    applyTruthPenalty(memoryId: string, penalty: number, reason: string): void;
-    delete(id: string): void;
-    /** v0.1.x behavior — returns full `Memory` rows. */
-    query(input: QueryInput & {
-        full: true;
-    }): Memory[];
-    /** v0.3.0 (BUG-001) — slim rows carrying the evidence fields. */
-    query(input: QueryInput & {
-        evidence: true;
-    }): SlimMemoryWithEvidence[];
-    /** v0.2.0 default — returns `SlimMemory` rows. */
-    query(input: QueryInput): SlimMemory[];
-    private isCrossProjectEnabled;
-    /**
-     * v0.4.0 (K4-012) — read a kevin_settings flag by key. Falls back to
-     * the caller-provided default when the key is missing or the table is
-     * unavailable (legacy DB without the settings table).
-     */
-    getSetting(key: string, fallback?: string): string;
-    private loadAll;
-    private queryRelevant;
-    getRelevant(input: GetRelevantInput): Memory[];
-    /**
-     * v0.4.0 (BUG-016) — apply the K2-023 relevance bump to a fixed slice
-     * of ids, exactly once. Lets ContextInjector probe without mutating
-     * and still bump the slice it actually injects.
-     */
-    bumpRelevance(ids: string[]): void;
-    /**
-     * v0.3.0 (K3-004) — Promote an error memory to a causal pattern.
-     *
-     * Creates a new `pattern` memory with `origin = 'causal'`, derived
-     * confidence, and evidence count. The original error memory is NOT
-     * deleted — the audit trail is preserved. Returns the new memory id,
-     * or null when the source error is not eligible (missing fingerprint,
-     * wrong type, or already promoted).
-     */
-    /**
-     * v0.4.0 (K4-009) — returns `{ id, created }` so callers can tell a
-     * newly-created pattern from an idempotent refresh.
-     */
-    promoteToPattern(errorId: string, evidenceCount: number, recurrenceCount?: number): {
-        id: string;
-        created: boolean;
-    } | null;
-    /**
-     * v0.2.0 (K2-026) — Feedback loop positive half (plan §B6.10 / D2-10).
-     *
-     * For each reflector-sourced error memory emitted during the given session
-     * whose fingerprint did NOT recur as a failing `tool_call` within the same
-     * project, bump `relevance_score` by `RELEVANCE_BUMP` (capped at
-     * `RELEVANCE_MAX`). Agent-saved memories are NEVER auto-boosted by this
-     * loop (anti-gaming guarantee, D2-06).
-     *
-     * Returns the number of memories that received a positive boost.
-     */
-    boostPositiveReflectors(sessionId: string): number;
-    /**
-     * v0.3.0 (K3-013) — Feedback loop negative half.
-     *
-     * For each reflector-sourced error memory from this session whose
-     * fingerprint DID recur as a failing tool_call (the lesson didn't
-     * prevent the error), decrement `relevance_score` by `RELEVANCE_PENALTY`
-     * (down to zero) and increment `evidence_count` as a negative signal.
-     * Agent-saved memories are NEVER penalized.
-     *
-     * Returns the number of memories penalized.
-     */
-    /**
-     * v0.3.0 fix — Mirror of the free function `countSupersedeCandidates`
-     * exposed as an instance method so `okf-import` (which holds a
-     * `MemoryService` reference but not the underlying `Store`) can count
-     * rows that `save()` will mark as superseded.
-     */
-    countSupersedeCandidates(type: MemoryType, fingerprint: string | null | undefined, projectId: string | null): number;
-    penalizeRecurringReflectors(sessionId: string): number;
-}
-/**
- * v0.3.0 fix — Extract `origin_call_id` from the memory metadata blob.
- *
- * Reflector stores the failing tool_call id in metadata.origin_call_id
- * (when available) so the feedback loop can exclude the original call
- * from the recurrence count. Returns null when metadata is absent,
- * malformed, or lacks the field.
- * // v1.1.0 (K11-003 / plan §5.5, D11-05) — single source for origin lookup;
- * // InjectionLedger reuses this implementation (K11-013).
- */
-export declare function readOriginCallId(metadata: string | null): string | null;
-/**
- * v0.3.0 fix — Count active memories that would be superseded by a new
- * row with the given (type, fingerprint, projectId) tuple. Used by
- * `okf-import` to populate `ImportResult.superseded` accurately.
- *
- * Matches the supersede logic in `save()`: only `decision` and `rule`
- * types supersede prior rows with the same fingerprint. Returns 0 for
- * any other type.
- */
-export declare function countSupersedeCandidates(store: Store, type: MemoryType, fingerprint: string | null | undefined, projectId: string | null): number;
-export {};